substrate-ai 0.20.64 → 0.20.65

package/dist/health-DC3y-sR6.js

@@ -0,0 +1,1715 @@
+import { createLogger } from "./logger-KeHncl-f.js";
+import { DoltClient, DoltQueryError, createDatabaseAdapter$1 as createDatabaseAdapter, getLatestRun, getPipelineRunById, initSchema } from "./dist-K_RRWnBX.js";
+import { resolveMainRepoRoot, resolveRunManifest } from "./manifest-read-DDkXC3L_.js";
+import { createRequire } from "module";
+import { dirname, join } from "path";
+import { existsSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join as join$1 } from "node:path";
+import { readFile, writeFile } from "node:fs/promises";
+import { existsSync as existsSync$1 } from "fs";
+import { createRequire as createRequire$1 } from "node:module";
+import { fileURLToPath } from "node:url";
+
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __commonJS = (cb, mod) => function() {
+	return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+//#endregion
+//#region src/persistence/adapter.ts
+/**
+* Create a DatabaseAdapter for the specified (or auto-detected) backend.
+*
+* This shim wraps the core factory and injects the concrete DoltClient
+* constructor as the doltClientFactory parameter, so monolith callers
+* get Dolt support transparently.
+*/
+function createDatabaseAdapter$1(config) {
+	return createDatabaseAdapter(config, (repoPath) => new DoltClient({ repoPath }));
+}
+
+//#endregion
+//#region src/modules/stop-after/types.ts
+/**
+* Stop-After Gate Module — Types
+*
+* Defines the PhaseName type and all parameter/result types for the stop-after gate.
+* VALID_PHASES is the canonical source for pipeline phase names; auto.ts imports from here.
+*/
+/** Canonical pipeline phase names. This is the single source of truth for all phase lists. */
+const VALID_PHASES = [
+	"research",
+	"analysis",
+	"planning",
+	"solutioning",
+	"implementation"
+];
+/**
+* Alias for VALID_PHASES retained for backward compatibility with existing imports.
+* @deprecated Use VALID_PHASES directly.
+*/
+const STOP_AFTER_VALID_PHASES = VALID_PHASES;
+
+//#endregion
+//#region src/cli/commands/pipeline-shared.ts
+/**
+* Parse a DB timestamp string to a Date, correctly treating it as UTC.
+*
+* SQLite stores timestamps as "YYYY-MM-DD HH:MM:SS" without a timezone suffix.
+* JavaScript's Date constructor parses strings without a timezone suffix as
+* *local time*, which causes staleness/duration to be calculated incorrectly
+* on machines not in UTC.
+*
+* Fix: append 'Z' if the string has no timezone marker so it is always
+* parsed as UTC.
+*/
+function parseDbTimestampAsUtc(ts) {
+	if (ts.endsWith("Z") || /[+-]\d{2}:\d{2}$/.test(ts)) return new Date(ts);
+	return new Date(ts.replace(" ", "T") + "Z");
+}
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+/**
+* Find the package root by walking up until we find package.json.
+* Works regardless of build output structure (tsdown bundles into
+* dist/cli/index.js, not dist/cli/commands/auto.js).
+*/
+function findPackageRoot(startDir) {
+	let dir = startDir;
+	while (dir !== dirname(dir)) {
+		if (existsSync$1(join(dir, "package.json"))) return dir;
+		dir = dirname(dir);
+	}
+	return startDir;
+}
+const PACKAGE_ROOT = join(__dirname, "..", "..", "..");
+/**
+* Resolve the absolute path to the bmad-method package's src/ directory.
+* Uses createRequire so it works in ESM without import.meta.resolve polyfills.
+* Returns null if bmad-method is not installed.
+*/
+function resolveBmadMethodSrcPath(fromDir = __dirname) {
+	try {
+		const require$1 = createRequire$1(join(fromDir, "synthetic.js"));
+		const pkgJsonPath = require$1.resolve("bmad-method/package.json");
+		return join(dirname(pkgJsonPath), "src");
+	} catch {
+		return null;
+	}
+}
+/**
+* Read the version field from bmad-method's package.json.
+* Returns 'unknown' if not resolvable.
+*/
+function resolveBmadMethodVersion(fromDir = __dirname) {
+	try {
+		const require$1 = createRequire$1(join(fromDir, "synthetic.js"));
+		const pkgJsonPath = require$1.resolve("bmad-method/package.json");
+		const pkg = require$1(pkgJsonPath);
+		return pkg.version ?? "unknown";
+	} catch {
+		return "unknown";
+	}
+}
+/** BMAD baseline token total for full pipeline comparison (analysis+planning+solutioning+implementation) */
+const BMAD_BASELINE_TOKENS_FULL = 56800;
+/** BMAD baseline token total for create+dev+review comparison */
+const BMAD_BASELINE_TOKENS = 23800;
+/** Story key pattern: e.g. "10-1", "1-1a", "NEW-26", "E6" */
+const STORY_KEY_PATTERN$1 = /^[A-Za-z0-9]+(-[A-Za-z0-9]+)?$/;
+/**
+* Top-level keys in .claude/settings.json that substrate owns.
+* On init, these are set/updated unconditionally.
+* User-defined keys outside this set are never touched.
+*/
+const SUBSTRATE_OWNED_SETTINGS_KEYS = ["statusLine"];
+function getSubstrateDefaultSettings() {
+	return { statusLine: {
+		type: "command",
+		command: "bash \"$CLAUDE_PROJECT_DIR\"/.claude/statusline.sh",
+		padding: 0
+	} };
+}
+/**
+* Format output according to the requested format.
+*/
+function formatOutput(data, format, success = true, errorMessage) {
+	if (format === "json") {
+		if (!success) return JSON.stringify({
+			success: false,
+			error: errorMessage ?? "Unknown error"
+		});
+		return JSON.stringify({
+			success: true,
+			data
+		});
+	}
+	if (typeof data === "string") return data;
+	return JSON.stringify(data, null, 2);
+}
+/**
+* Build a human-readable token telemetry display from summary rows.
+*/
+function formatTokenTelemetry(summary, baselineTokens = BMAD_BASELINE_TOKENS) {
+	if (summary.length === 0) return "No token usage recorded.";
+	let totalInput = 0;
+	let totalOutput = 0;
+	let totalCost = 0;
+	const lines = ["Pipeline Token Usage:"];
+	for (const row of summary) {
+		totalInput += row.total_input_tokens;
+		totalOutput += row.total_output_tokens;
+		totalCost += row.total_cost_usd;
+		const cost = `$${row.total_cost_usd.toFixed(4)}`;
+		lines.push(`  ${row.phase} (${row.agent}): ${row.total_input_tokens.toLocaleString()} input / ${row.total_output_tokens.toLocaleString()} output (${cost})`);
+	}
+	lines.push("  " + "─".repeat(55));
+	const costDisplay = `$${totalCost.toFixed(4)}`;
+	lines.push(`  Total:  ${totalInput.toLocaleString()} input / ${totalOutput.toLocaleString()} output (${costDisplay})`);
+	const totalTokens = totalInput + totalOutput;
+	const savingsPct = baselineTokens > 0 ? Math.round((baselineTokens - totalTokens) / baselineTokens * 100) : 0;
+	const savingsLabel = savingsPct >= 0 ? `Savings: ${savingsPct}%` : `Overhead: +${Math.abs(savingsPct)}%`;
+	lines.push(`  BMAD Baseline: ${baselineTokens.toLocaleString()} tokens → ${savingsLabel}`);
+	return lines.join("\n");
+}
+/**
+* Validate a story key has the expected format: <epic>-<story> (e.g., "10-1").
+*/
+function validateStoryKey(key) {
+	return STORY_KEY_PATTERN$1.test(key);
+}
+/**
+* Build the AC5 JSON status schema for a pipeline run.
+*/
+function buildPipelineStatusOutput(run, tokenSummary, decisionsCount, storiesCount) {
+	const phases = {};
+	const phaseTokenMap = {};
+	for (const row of tokenSummary) {
+		if (!phaseTokenMap[row.phase]) phaseTokenMap[row.phase] = {
+			input: 0,
+			output: 0
+		};
+		phaseTokenMap[row.phase].input += row.total_input_tokens;
+		phaseTokenMap[row.phase].output += row.total_output_tokens;
+	}
+	let phaseHistory = [];
+	try {
+		if (run.config_json) {
+			const config = JSON.parse(run.config_json);
+			phaseHistory = config.phaseHistory ?? [];
+		}
+	} catch {}
+	const currentPhase = run.current_phase ?? null;
+	for (const phaseName of VALID_PHASES) {
+		const historyEntry = phaseHistory.find((h) => h.phase === phaseName);
+		const tokenUsage = phaseTokenMap[phaseName] ?? {
+			input: 0,
+			output: 0
+		};
+		if (historyEntry?.completedAt) {
+			phases[phaseName] = {
+				status: "complete",
+				completed_at: historyEntry.completedAt,
+				token_usage: tokenUsage
+			};
+			if (historyEntry.startedAt) phases[phaseName].started_at = historyEntry.startedAt;
+		} else if (phaseName === currentPhase || historyEntry?.startedAt) phases[phaseName] = {
+			status: "running",
+			started_at: historyEntry?.startedAt,
+			token_usage: tokenUsage
+		};
+		else phases[phaseName] = { status: "pending" };
+	}
+	let totalInput = 0;
+	let totalOutput = 0;
+	let totalCost = 0;
+	for (const row of tokenSummary) {
+		totalInput += row.total_input_tokens;
+		totalOutput += row.total_output_tokens;
+		totalCost += row.total_cost_usd;
+	}
+	let activeDispatches = 0;
+	let storiesSummary;
+	try {
+		if (run.token_usage_json) {
+			const state = JSON.parse(run.token_usage_json);
+			if (state.stories && Object.keys(state.stories).length > 0) {
+				const now = Date.now();
+				let completed = 0;
+				let inProgress = 0;
+				let escalated = 0;
+				let pending = 0;
+				const details = {};
+				for (const [key, s] of Object.entries(state.stories)) {
+					const phase = s.phase ?? "PENDING";
+					if (phase !== "PENDING" && phase !== "COMPLETE" && phase !== "ESCALATED") activeDispatches++;
+					if (phase === "COMPLETE") completed++;
+					else if (phase === "ESCALATED") escalated++;
+					else if (phase === "PENDING") pending++;
+					else inProgress++;
+					const elapsed = s.startedAt != null ? Math.max(0, Math.round((now - new Date(s.startedAt).getTime()) / 1e3)) : 0;
+					details[key] = {
+						phase,
+						review_cycles: s.reviewCycles ?? 0,
+						elapsed_seconds: elapsed
+					};
+				}
+				storiesSummary = {
+					completed,
+					in_progress: inProgress,
+					escalated,
+					pending,
+					details
+				};
+			}
+		}
+	} catch {}
+	const derivedStoriesCount = storiesSummary !== void 0 ? storiesSummary.completed + storiesSummary.in_progress + storiesSummary.escalated + storiesSummary.pending : storiesCount;
+	const derivedStoriesCompleted = storiesSummary !== void 0 ? storiesSummary.completed : 0;
+	return {
+		run_id: run.id,
+		current_phase: currentPhase,
+		phases,
+		total_tokens: {
+			input: totalInput,
+			output: totalOutput,
+			cost_usd: totalCost
+		},
+		decisions_count: decisionsCount,
+		stories_count: derivedStoriesCount,
+		stories_completed: derivedStoriesCompleted,
+		last_activity: run.updated_at ?? "",
+		staleness_seconds: Math.round((Date.now() - parseDbTimestampAsUtc(run.updated_at ?? "").getTime()) / 1e3),
+		last_event_ts: run.updated_at ?? "",
+		active_dispatches: activeDispatches,
+		...storiesSummary !== void 0 ? { stories: storiesSummary } : {}
+	};
+}
+/**
+* Format a pipeline status summary in human-readable format.
+*/
+function formatPipelineStatusHuman(status) {
+	const lines = [];
+	lines.push(`Pipeline Run: ${status.run_id}`);
+	lines.push(`  Current Phase: ${status.current_phase ?? "N/A"}`);
+	lines.push("");
+	lines.push("  Phase Status:");
+	const statusIcons = {
+		complete: "[DONE]",
+		running: "[RUN] ",
+		pending: "[    ]"
+	};
+	for (const [phaseName, phaseInfo] of Object.entries(status.phases)) {
+		const icon = statusIcons[phaseInfo.status] ?? "[?]";
+		let line = `    ${icon} ${phaseName}`;
+		if (phaseInfo.status === "complete" && phaseInfo.completed_at) line += ` (completed: ${phaseInfo.completed_at})`;
+		if (phaseInfo.token_usage && (phaseInfo.token_usage.input > 0 || phaseInfo.token_usage.output > 0)) line += ` — tokens: ${phaseInfo.token_usage.input.toLocaleString()} in / ${phaseInfo.token_usage.output.toLocaleString()} out`;
+		lines.push(line);
+	}
+	lines.push("");
+	lines.push(`  Total Tokens: ${(status.total_tokens.input + status.total_tokens.output).toLocaleString()} (in: ${status.total_tokens.input.toLocaleString()}, out: ${status.total_tokens.output.toLocaleString()})`);
+	lines.push(`  Total Cost: $${status.total_tokens.cost_usd.toFixed(4)}`);
+	lines.push(`  Decisions: ${status.decisions_count}`);
+	lines.push(`  Stories: ${status.stories_count}`);
+	if (status.stories !== void 0 && Object.keys(status.stories.details).length > 0) {
+		lines.push("");
+		lines.push("  Sprint Progress:");
+		lines.push("  " + "─".repeat(68));
+		lines.push(`  ${"STORY".padEnd(10)} ${"PHASE".padEnd(24)} ${"CYCLES".padEnd(8)} ELAPSED`);
+		lines.push("  " + "─".repeat(68));
+		for (const [key, detail] of Object.entries(status.stories.details)) {
+			const elapsed = detail.elapsed_seconds > 0 ? `${detail.elapsed_seconds}s` : "-";
+			lines.push(`  ${key.padEnd(10)} ${detail.phase.padEnd(24)} ${String(detail.review_cycles).padEnd(8)} ${elapsed}`);
+		}
+		lines.push("  " + "─".repeat(68));
+		lines.push(`  Completed: ${status.stories.completed}  In Progress: ${status.stories.in_progress}  Escalated: ${status.stories.escalated}  Pending: ${status.stories.pending}`);
+	}
+	return lines.join("\n");
+}
+/**
+* Format a complete pipeline run summary.
+*/
+function formatPipelineSummary(run, tokenSummary, decisionsCount, storiesCount, durationMs, format) {
+	let totalInput = 0;
+	let totalOutput = 0;
+	let totalCost = 0;
+	for (const row of tokenSummary) {
+		totalInput += row.total_input_tokens;
+		totalOutput += row.total_output_tokens;
+		totalCost += row.total_cost_usd;
+	}
+	const totalTokens = totalInput + totalOutput;
+	const savingsPct = BMAD_BASELINE_TOKENS_FULL > 0 ? Math.round((BMAD_BASELINE_TOKENS_FULL - totalTokens) / BMAD_BASELINE_TOKENS_FULL * 100) : 0;
+	const durationSec = Math.round(durationMs / 1e3);
+	if (format === "json") return JSON.stringify({
+		run_id: run.id,
+		status: run.status,
+		duration_ms: durationMs,
+		phases_completed: VALID_PHASES.length,
+		decisions_count: decisionsCount,
+		stories_count: storiesCount,
+		token_usage: {
+			input: totalInput,
+			output: totalOutput,
+			total: totalTokens,
+			cost_usd: totalCost,
+			bmad_baseline: BMAD_BASELINE_TOKENS_FULL,
+			savings_pct: savingsPct
+		}
+	});
+	const lines = [
+		"┌─────────────────────────────────────────────────────┐",
+		"│              Pipeline Run Summary                    │",
+		"└─────────────────────────────────────────────────────┘",
+		`  Run ID:          ${run.id}`,
+		`  Status:          ${run.status}`,
+		`  Duration:        ${durationSec}s`,
+		`  Phases Complete: ${VALID_PHASES.length}`,
+		`  Decisions:       ${decisionsCount}`,
+		`  Stories:         ${storiesCount}`,
+		"",
+		`  Token Usage:     ${totalTokens.toLocaleString()} total`,
+		`    Input:         ${totalInput.toLocaleString()}`,
+		`    Output:        ${totalOutput.toLocaleString()}`,
+		`    Cost:          $${totalCost.toFixed(4)}`,
+		"",
+		`  BMAD Baseline:   ${BMAD_BASELINE_TOKENS_FULL.toLocaleString()} tokens`,
+		`  Token Savings:   ${savingsPct >= 0 ? savingsPct + "%" : "N/A (overhead)"}`
+	];
+	return lines.join("\n");
+}
+
+//#endregion
+//#region src/modules/state/file-store.ts
+/**
+* In-memory / file-backed StateStore implementation.
+*
+* Suitable for CI environments and testing where orchestrator state is
+* ephemeral. Use DoltStateStore for branch-per-story isolation and versioned
+* history in production.
+*/
+var FileStateStore = class {
+	_basePath;
+	_stories = new Map();
+	_metrics = [];
+	_contracts = new Map();
+	_contractVerifications = new Map();
+	/** Key-value metrics store: outer key = runId, inner key = metric key */
+	_kvMetrics = new Map();
+	constructor(options = {}) {
+		this._basePath = options.basePath;
+	}
+	async initialize() {}
+	async close() {}
+	async getStoryState(storyKey) {
+		return this._stories.get(storyKey);
+	}
+	async setStoryState(storyKey, state) {
+		this._stories.set(storyKey, {
+			...state,
+			storyKey
+		});
+	}
+	async queryStories(filter) {
+		const all = Array.from(this._stories.values());
+		return all.filter((record) => {
+			if (filter.phase !== void 0) {
+				const phases = Array.isArray(filter.phase) ? filter.phase : [filter.phase];
+				if (!phases.includes(record.phase)) return false;
+			}
+			if (filter.sprint !== void 0 && record.sprint !== filter.sprint) return false;
+			if (filter.storyKey !== void 0 && record.storyKey !== filter.storyKey) return false;
+			return true;
+		});
+	}
+	async recordMetric(metric) {
+		const record = {
+			...metric,
+			recordedAt: metric.recordedAt ?? new Date().toISOString()
+		};
+		this._metrics.push(record);
+	}
+	async queryMetrics(filter) {
+		const storyKey = filter.storyKey ?? filter.story_key;
+		const taskType = filter.taskType ?? filter.task_type;
+		return this._metrics.filter((m) => {
+			if (storyKey !== void 0 && m.storyKey !== storyKey) return false;
+			if (taskType !== void 0 && m.taskType !== taskType) return false;
+			if (filter.sprint !== void 0 && m.sprint !== filter.sprint) return false;
+			if (filter.dateFrom !== void 0 && m.recordedAt !== void 0 && m.recordedAt < filter.dateFrom) return false;
+			if (filter.dateTo !== void 0 && m.recordedAt !== void 0 && m.recordedAt > filter.dateTo) return false;
+			if (filter.since !== void 0 && m.recordedAt !== void 0 && m.recordedAt < filter.since) return false;
+			return true;
+		});
+	}
+	/**
+	* Persist an arbitrary key-value metric for a run.
+	* Stored in memory AND written to `{basePath}/kv-metrics.json` when basePath is set.
+	*/
+	async setMetric(runId, key, value) {
+		let runMap = this._kvMetrics.get(runId);
+		if (runMap === void 0) {
+			runMap = new Map();
+			this._kvMetrics.set(runId, runMap);
+		}
+		runMap.set(key, value);
+		if (this._basePath !== void 0) await this._flushKvMetrics();
+	}
+	/**
+	* Retrieve a previously stored key-value metric for a run.
+	* Reads from in-memory cache, falling back to the JSON file when basePath is set.
+	*/
+	async getMetric(runId, key) {
+		const inMemory = this._kvMetrics.get(runId)?.get(key);
+		if (inMemory !== void 0) return inMemory;
+		if (this._basePath !== void 0) try {
+			const filePath = join$1(this._basePath, "kv-metrics.json");
+			const content = await readFile(filePath, "utf-8");
+			const parsed = JSON.parse(content);
+			return parsed[runId]?.[key] ?? void 0;
+		} catch {}
+		return void 0;
+	}
+	/** Serialize the in-memory kv metrics map to JSON on disk. */
+	async _flushKvMetrics() {
+		if (this._basePath === void 0) return;
+		const serialized = {};
+		for (const [runId, runMap] of this._kvMetrics) {
+			serialized[runId] = {};
+			for (const [key, value] of runMap) serialized[runId][key] = value;
+		}
+		const filePath = join$1(this._basePath, "kv-metrics.json");
+		await writeFile(filePath, JSON.stringify(serialized, null, 2), "utf-8");
+	}
+	async getContracts(storyKey) {
+		return this._contracts.get(storyKey) ?? [];
+	}
+	async setContracts(storyKey, contracts) {
+		this._contracts.set(storyKey, contracts.map((c) => ({ ...c })));
+	}
+	async queryContracts(filter) {
+		const all = [];
+		for (const records of this._contracts.values()) for (const r of records) all.push(r);
+		return all.filter((r) => {
+			if (filter?.storyKey !== void 0 && r.storyKey !== filter.storyKey) return false;
+			if (filter?.direction !== void 0 && r.direction !== filter.direction) return false;
+			return true;
+		});
+	}
+	async setContractVerification(storyKey, results) {
+		this._contractVerifications.set(storyKey, results.map((r) => ({ ...r })));
+		if (this._basePath !== void 0) {
+			const serialized = {};
+			for (const [key, records] of this._contractVerifications) serialized[key] = records;
+			const filePath = join$1(this._basePath, "contract-verifications.json");
+			await writeFile(filePath, JSON.stringify(serialized, null, 2), "utf-8");
+		}
+	}
+	async getContractVerification(storyKey) {
+		return this._contractVerifications.get(storyKey) ?? [];
+	}
+	async branchForStory(_storyKey) {}
+	async mergeStory(_storyKey) {}
+	async rollbackStory(_storyKey) {}
+	async diffStory(storyKey) {
+		return {
+			storyKey,
+			tables: []
+		};
+	}
+	async getHistory(_limit) {
+		return [];
+	}
+};
+
+//#endregion
+//#region src/modules/state/errors.ts
+/**
+* Typed error classes for the Dolt state store.
+*/
+var StateStoreError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "StateStoreError";
+		this.code = code;
+	}
+};
+var DoltMergeConflictError = class extends StateStoreError {
+	table;
+	conflictingKeys;
+	rowKey;
+	ourValue;
+	theirValue;
+	constructor(table, conflictingKeys, options) {
+		super("DOLT_MERGE_CONFLICT", `Merge conflict in table '${table}' on keys: ${conflictingKeys.join(", ")}`);
+		this.name = "DoltMergeConflictError";
+		this.table = table;
+		this.conflictingKeys = conflictingKeys;
+		if (options) {
+			this.rowKey = options.rowKey;
+			this.ourValue = options.ourValue;
+			this.theirValue = options.theirValue;
+		}
+	}
+};
+/** Alias for DoltMergeConflictError — used by orchestrator branch lifecycle. */
+const DoltMergeConflict = DoltMergeConflictError;
+
+//#endregion
+//#region src/modules/state/dolt-store.ts
+const log = createLogger("modules:state:dolt");
+/**
+* Validate that a story key matches the expected pattern (e.g. "26-7", "1-1a", "NEW-26", "E6").
+* Prevents SQL injection via string-interpolated identifiers.
+*/
+const STORY_KEY_PATTERN = /^[A-Za-z0-9]+(-[A-Za-z0-9]+)?$/;
+function assertValidStoryKey(storyKey) {
+	if (!STORY_KEY_PATTERN.test(storyKey)) throw new DoltQueryError("assertValidStoryKey", `Invalid story key: '${storyKey}'. Must match pattern <key> or <epic>-<story> (e.g. "E6", "10-1", "1-1a", "NEW-26").`);
+}
+/**
+* Dolt-backed implementation of the StateStore interface.
+*
+* Constructor accepts a deps object for DI: `{ repoPath, client }`.
+* Call `initialize()` before any CRUD operations.
+*/
+var DoltStateStore = class DoltStateStore {
+	_repoPath;
+	_client;
+	_storyBranches = new Map();
+	constructor(options) {
+		this._repoPath = options.repoPath;
+		this._client = options.client;
+	}
+	/**
+	* Return the branch name for a story if one has been created via branchForStory(),
+	* or undefined to use the default (main) branch.
+	*/
+	_branchFor(storyKey) {
+		return this._storyBranches.get(storyKey);
+	}
+	async initialize() {
+		await this._client.connect();
+		await this._runMigrations();
+		await this.flush("substrate: schema migrations");
+		log.debug("DoltStateStore initialized at %s", this._repoPath);
+	}
+	async close() {
+		await this._client.close();
+	}
+	async _runMigrations() {
+		const ddl = [
+			`CREATE TABLE IF NOT EXISTS stories (
+        story_key     VARCHAR(100) NOT NULL,
+        phase         VARCHAR(30)  NOT NULL DEFAULT 'PENDING',
+        review_cycles INT          NOT NULL DEFAULT 0,
+        last_verdict  VARCHAR(64)  NULL,
+        error         TEXT         NULL,
+        started_at    VARCHAR(64)  NULL,
+        completed_at  VARCHAR(64)  NULL,
+        sprint        VARCHAR(50)  NULL,
+        PRIMARY KEY (story_key)
+      )`,
+			`CREATE TABLE IF NOT EXISTS metrics (
+        id              BIGINT       NOT NULL AUTO_INCREMENT,
+        story_key       VARCHAR(100) NOT NULL,
+        task_type       VARCHAR(100) NOT NULL,
+        model           VARCHAR(100) NULL,
+        tokens_in       BIGINT       NULL,
+        tokens_out      BIGINT       NULL,
+        cache_read_tokens BIGINT     NULL,
+        cost_usd        DOUBLE       NULL,
+        wall_clock_ms   BIGINT       NULL,
+        review_cycles   INT          NULL,
+        stall_count     INT          NULL,
+        result          VARCHAR(30)  NULL,
+        recorded_at     VARCHAR(64)  NULL,
+        sprint          VARCHAR(50)  NULL,
+        PRIMARY KEY (id)
+      )`,
+			`CREATE TABLE IF NOT EXISTS contracts (
+        story_key     VARCHAR(100) NOT NULL,
+        contract_name VARCHAR(200) NOT NULL,
+        direction     VARCHAR(20)  NOT NULL,
+        schema_path   VARCHAR(500) NULL,
+        transport     VARCHAR(200) NULL,
+        PRIMARY KEY (story_key, contract_name, direction)
+      )`,
+			`CREATE TABLE IF NOT EXISTS review_verdicts (
+        id            BIGINT       NOT NULL AUTO_INCREMENT,
+        story_key     VARCHAR(100) NOT NULL,
+        task_type     VARCHAR(100) NOT NULL,
+        verdict       VARCHAR(64)  NOT NULL,
+        issues_count  INT          NULL,
+        notes         TEXT         NULL,
+        timestamp     VARCHAR(64)  NULL,
+        PRIMARY KEY (id)
+      )`
+		];
+		for (const sql of ddl) await this._client.query(sql);
+		try {
+			const colRows = await this._client.query(`SHOW COLUMNS FROM repo_map_symbols LIKE 'dependencies'`);
+			if (colRows.length === 0) {
+				await this._client.query(`ALTER TABLE repo_map_symbols ADD COLUMN dependencies JSON`);
+				await this._client.query(`INSERT IGNORE INTO _schema_version (version, description) VALUES (6, 'Add dependencies JSON column to repo_map_symbols (Epic 28-3)')`);
+				log.info({
+					component: "dolt-state",
+					migration: "v5-to-v6",
+					column: "dependencies",
+					table: "repo_map_symbols"
+				}, "Applied migration v5-to-v6: added dependencies column to repo_map_symbols");
+			}
+		} catch {
+			log.debug("Skipping repo_map_symbols migration: table not yet created");
+		}
+		log.debug("Schema migrations applied");
+	}
+	/**
+	* Commit pending Dolt changes on the current branch.
+	* Callers can invoke this after a batch of writes for explicit durability.
+	*/
+	async flush(message = "substrate: auto-commit") {
+		try {
+			await this._client.execArgs(["add", "."]);
+			await this._client.execArgs([
+				"commit",
+				"--allow-empty",
+				"-m",
+				message
+			]);
+			log.debug("Dolt flush committed: %s", message);
+		} catch (err) {
+			const detail = err instanceof Error ? err.message : String(err);
+			log.warn({ detail }, "Dolt flush failed (non-fatal)");
+		}
+	}
+	async getStoryState(storyKey) {
+		const rows = await this._client.query("SELECT * FROM stories WHERE story_key = ?", [storyKey]);
+		if (rows.length === 0) return void 0;
+		return this._rowToStory(rows[0]);
+	}
+	async setStoryState(storyKey, state) {
+		const branch = this._branchFor(storyKey);
+		const sql = `REPLACE INTO stories
+      (story_key, phase, review_cycles, last_verdict, error, started_at, completed_at, sprint)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)`;
+		await this._client.query(sql, [
+			storyKey,
+			state.phase,
+			state.reviewCycles,
+			state.lastVerdict ?? null,
+			state.error ?? null,
+			state.startedAt ?? null,
+			state.completedAt ?? null,
+			state.sprint ?? null
+		], branch);
+	}
+	async queryStories(filter) {
+		const conditions = [];
+		const params = [];
+		if (filter.phase !== void 0) {
+			const phases = Array.isArray(filter.phase) ? filter.phase : [filter.phase];
+			const placeholders = phases.map(() => "?").join(", ");
+			conditions.push(`phase IN (${placeholders})`);
+			params.push(...phases);
+		}
+		if (filter.sprint !== void 0) {
+			conditions.push("sprint = ?");
+			params.push(filter.sprint);
+		}
+		if (filter.storyKey !== void 0) {
+			conditions.push("story_key = ?");
+			params.push(filter.storyKey);
+		}
+		const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+		const sql = `SELECT * FROM stories ${where} ORDER BY story_key`;
+		const rows = await this._client.query(sql, params);
+		return rows.map((r) => this._rowToStory(r));
+	}
+	_rowToStory(row) {
+		return {
+			storyKey: row.story_key,
+			phase: row.phase,
+			reviewCycles: Number(row.review_cycles),
+			lastVerdict: row.last_verdict ?? void 0,
+			error: row.error ?? void 0,
+			startedAt: row.started_at ?? void 0,
+			completedAt: row.completed_at ?? void 0,
+			sprint: row.sprint ?? void 0
+		};
+	}
+	async recordMetric(metric) {
+		const branch = this._branchFor(metric.storyKey);
+		const recordedAt = metric.recordedAt ?? metric.timestamp ?? new Date().toISOString();
+		const sql = `INSERT INTO metrics
+      (story_key, task_type, model, tokens_in, tokens_out, cache_read_tokens,
+       cost_usd, wall_clock_ms, review_cycles, stall_count, result, recorded_at, sprint)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`;
+		await this._client.query(sql, [
+			metric.storyKey,
+			metric.taskType,
+			metric.model ?? null,
+			metric.tokensIn ?? null,
+			metric.tokensOut ?? null,
+			metric.cacheReadTokens ?? null,
+			metric.costUsd ?? null,
+			metric.wallClockMs ?? null,
+			metric.reviewCycles ?? null,
+			metric.stallCount ?? null,
+			metric.result ?? null,
+			recordedAt,
+			metric.sprint ?? null
+		], branch);
+	}
+	async queryMetrics(filter) {
+		const conditions = [];
+		const params = [];
+		const storyKey = filter.storyKey ?? filter.story_key;
+		const taskType = filter.taskType ?? filter.task_type;
+		if (storyKey !== void 0) {
+			conditions.push("story_key = ?");
+			params.push(storyKey);
+		}
+		if (taskType !== void 0) {
+			conditions.push("task_type = ?");
+			params.push(taskType);
+		}
+		if (filter.sprint !== void 0) {
+			conditions.push("sprint = ?");
+			params.push(filter.sprint);
+		}
+		if (filter.dateFrom !== void 0) {
+			conditions.push("recorded_at >= ?");
+			params.push(filter.dateFrom);
+		}
+		if (filter.dateTo !== void 0) {
+			conditions.push("recorded_at <= ?");
+			params.push(filter.dateTo);
+		}
+		if (filter.since !== void 0) {
+			conditions.push("recorded_at >= ?");
+			params.push(filter.since);
+		}
+		const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+		if (filter.aggregate) {
+			const sql$1 = `SELECT task_type,
+        AVG(cost_usd) AS avg_cost_usd,
+        SUM(tokens_in) AS sum_tokens_in,
+        SUM(tokens_out) AS sum_tokens_out,
+        COUNT(*) AS count
+        FROM metrics ${where} GROUP BY task_type ORDER BY task_type`;
+			const aggRows = await this._client.query(sql$1, params);
+			return aggRows.map((r) => this._aggregateRowToMetric(r));
+		}
+		const sql = `SELECT * FROM metrics ${where} ORDER BY id`;
+		const rows = await this._client.query(sql, params);
+		return rows.map((r) => this._rowToMetric(r));
+	}
+	_aggregateRowToMetric(row) {
+		return {
+			storyKey: "",
+			taskType: row.task_type,
+			costUsd: row.avg_cost_usd ?? void 0,
+			tokensIn: row.sum_tokens_in ?? void 0,
+			tokensOut: row.sum_tokens_out ?? void 0,
+			count: row.count,
+			result: "aggregate"
+		};
+	}
+	_rowToMetric(row) {
+		return {
+			storyKey: row.story_key,
+			taskType: row.task_type,
+			model: row.model ?? void 0,
+			tokensIn: row.tokens_in ?? void 0,
+			tokensOut: row.tokens_out ?? void 0,
+			cacheReadTokens: row.cache_read_tokens ?? void 0,
+			costUsd: row.cost_usd ?? void 0,
+			wallClockMs: row.wall_clock_ms ?? void 0,
+			reviewCycles: row.review_cycles ?? void 0,
+			stallCount: row.stall_count ?? void 0,
+			result: row.result ?? void 0,
+			recordedAt: row.recorded_at ?? void 0,
+			sprint: row.sprint ?? void 0,
+			timestamp: row.timestamp ?? row.recorded_at ?? void 0
+		};
+	}
+	async getContracts(storyKey) {
+		const rows = await this._client.query("SELECT * FROM contracts WHERE story_key = ? ORDER BY contract_name", [storyKey]);
+		return rows.map((r) => this._rowToContract(r));
+	}
+	async setContracts(storyKey, contracts) {
+		const branch = this._branchFor(storyKey);
+		await this._client.query("DELETE FROM contracts WHERE story_key = ?", [storyKey], branch);
+		for (const c of contracts) await this._client.query(`INSERT INTO contracts (story_key, contract_name, direction, schema_path, transport)
+         VALUES (?, ?, ?, ?, ?)`, [
+			c.storyKey,
+			c.contractName,
+			c.direction,
+			c.schemaPath,
+			c.transport ?? null
+		], branch);
+	}
+	_rowToContract(row) {
+		return {
+			storyKey: row.story_key,
+			contractName: row.contract_name,
+			direction: row.direction,
+			schemaPath: row.schema_path,
+			transport: row.transport ?? void 0
+		};
+	}
+	async queryContracts(filter) {
+		const conditions = [];
+		const params = [];
+		if (filter?.storyKey !== void 0) {
+			conditions.push("story_key = ?");
+			params.push(filter.storyKey);
+		}
+		if (filter?.direction !== void 0) {
+			conditions.push("direction = ?");
+			params.push(filter.direction);
+		}
+		const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+		const sql = `SELECT * FROM contracts ${where} ORDER BY story_key, contract_name`;
+		const rows = await this._client.query(sql, params);
+		return rows.map((r) => this._rowToContract(r));
+	}
+	async setContractVerification(storyKey, results) {
+		const branch = this._branchFor(storyKey);
+		await this._client.query(`DELETE FROM review_verdicts WHERE story_key = ? AND task_type = 'contract-verification'`, [storyKey], branch);
+		const failCount = results.filter((r) => r.verdict === "fail").length;
+		for (const r of results) await this._client.query(`INSERT INTO review_verdicts (story_key, task_type, verdict, issues_count, notes, timestamp)
+         VALUES (?, 'contract-verification', ?, ?, ?, ?)`, [
+			storyKey,
+			r.verdict,
+			failCount,
+			JSON.stringify({
+				contractName: r.contractName,
+				mismatchDescription: r.mismatchDescription
+			}),
+			r.verifiedAt
+		], branch);
+	}
+	async getContractVerification(storyKey) {
+		const rows = await this._client.query(`SELECT * FROM review_verdicts WHERE story_key = ? AND task_type = 'contract-verification' ORDER BY timestamp DESC`, [storyKey]);
+		return rows.map((row) => {
+			let contractName = "";
+			let mismatchDescription;
+			if (row.notes !== null) try {
+				const parsed = JSON.parse(row.notes);
+				if (typeof parsed.contractName === "string") contractName = parsed.contractName;
+				if (typeof parsed.mismatchDescription === "string") mismatchDescription = parsed.mismatchDescription;
+			} catch {}
+			return {
+				storyKey: row.story_key,
+				contractName,
+				verdict: row.verdict,
+				...mismatchDescription !== void 0 ? { mismatchDescription } : {},
+				verifiedAt: row.timestamp ?? new Date().toISOString()
+			};
+		});
+	}
+	async branchForStory(storyKey) {
+		assertValidStoryKey(storyKey);
+		const branchName = `story/${storyKey}`;
+		try {
+			await this._client.query(`CALL DOLT_BRANCH('${branchName}')`, [], "main");
+			this._storyBranches.set(storyKey, branchName);
+			log.debug("Created Dolt branch %s for story %s", branchName, storyKey);
+		} catch (err) {
+			const detail = err instanceof Error ? err.message : String(err);
+			throw new DoltQueryError(`CALL DOLT_BRANCH('${branchName}')`, detail);
+		}
+	}
+	async mergeStory(storyKey) {
+		assertValidStoryKey(storyKey);
+		const branchName = this._storyBranches.get(storyKey);
+		if (branchName === void 0) {
+			log.warn({ storyKey }, "mergeStory called but no branch registered — no-op");
+			return;
+		}
+		try {
+			try {
+				await this._client.query(`CALL DOLT_ADD('-A')`, [], branchName);
+				await this._client.query(`CALL DOLT_COMMIT('-m', 'Story ${storyKey}: pre-merge commit', '--allow-empty')`, [], branchName);
+			} catch {}
+			try {
+				await this._client.query(`CALL DOLT_ADD('-A')`, [], "main");
+				await this._client.query(`CALL DOLT_COMMIT('-m', 'substrate: pre-merge auto-commit', '--allow-empty')`, [], "main");
+			} catch {}
+			const mergeRows = await this._client.query(`CALL DOLT_MERGE('${branchName}')`, [], "main");
+			const mergeResult = mergeRows[0];
+			if (mergeResult && (mergeResult.conflicts ?? 0) > 0) {
+				let table = "stories";
+				let rowKey = "unknown";
+				let ourValue;
+				let theirValue;
+				try {
+					const conflictRows = await this._client.query(`SELECT * FROM dolt_conflicts_stories LIMIT 1`, [], "main");
+					if (conflictRows.length > 0) {
+						const row = conflictRows[0];
+						rowKey = String(row["base_story_key"] ?? row["our_story_key"] ?? "unknown");
+						ourValue = JSON.stringify(row["our_status"] ?? row);
+						theirValue = JSON.stringify(row["their_status"] ?? row);
+					}
+				} catch {}
+				this._storyBranches.delete(storyKey);
+				throw new DoltMergeConflictError(table, [rowKey], {
+					rowKey,
+					ourValue,
+					theirValue
+				});
+			}
+			try {
+				await this._client.query(`CALL DOLT_COMMIT('-m', 'Merge story ${storyKey}: COMPLETE')`, [], "main");
+			} catch (commitErr) {
+				const msg = commitErr instanceof Error ? commitErr.message : String(commitErr);
+				if (!msg.includes("nothing to commit")) throw commitErr;
+			}
+			this._storyBranches.delete(storyKey);
+			log.debug("Merged branch %s into main for story %s", branchName, storyKey);
+		} catch (err) {
+			if (err instanceof DoltMergeConflictError) throw err;
+			const detail = err instanceof Error ? err.message : String(err);
+			throw new DoltQueryError(`CALL DOLT_MERGE('${branchName}')`, detail);
+		}
+	}
+	async rollbackStory(storyKey) {
+		assertValidStoryKey(storyKey);
+		const branchName = this._storyBranches.get(storyKey);
+		if (branchName === void 0) {
+			log.warn({ storyKey }, "rollbackStory called but no branch registered — no-op");
+			return;
+		}
+		try {
+			await this._client.query(`CALL DOLT_BRANCH('-D', '${branchName}')`, [], "main");
+			this._storyBranches.delete(storyKey);
+			log.debug("Rolled back (deleted) branch %s for story %s", branchName, storyKey);
+		} catch (err) {
+			const detail = err instanceof Error ? err.message : String(err);
+			log.warn({
+				detail,
+				storyKey,
+				branchName
+			}, "rollbackStory failed (non-fatal)");
+			this._storyBranches.delete(storyKey);
+		}
+	}
+	/**
+	* Tables queried by diffStory(). Each table is checked for row-level changes
+	* via SELECT * FROM DOLT_DIFF('main', branchName, tableName).
+	*/
+	static DIFF_TABLES = [
+		"stories",
+		"contracts",
+		"metrics",
+		"dispatch_log",
+		"build_results",
+		"review_verdicts"
+	];
+	async diffStory(storyKey) {
+		assertValidStoryKey(storyKey);
+		const branchName = this._storyBranches.get(storyKey);
+		if (branchName === void 0) return this._diffMergedStory(storyKey);
+		try {
+			await this._client.query(`CALL DOLT_ADD('-A')`, [], branchName);
+			await this._client.query(`CALL DOLT_COMMIT('-m', 'Story ${storyKey}: pre-diff snapshot', '--allow-empty')`, [], branchName);
+		} catch {}
+		return this._diffRange("main", branchName, storyKey);
+	}
+	/**
+	* Diff a merged story by finding its merge commit in the Dolt log.
+	* Queries the `dolt_log` system table for commits referencing the story,
+	* then diffs `<hash>~1` vs `<hash>` for row-level changes.
+	*/
+	async _diffMergedStory(storyKey) {
+		try {
+			const rows = await this._client.query(`SELECT commit_hash FROM dolt_log WHERE message LIKE ? LIMIT 1`, [`%${storyKey}%`]);
+			if (rows.length === 0) return {
+				storyKey,
+				tables: []
+			};
+			const hash = String(rows[0].commit_hash);
+			if (!hash) return {
+				storyKey,
+				tables: []
+			};
+			return this._diffRange(`${hash}~1`, hash, storyKey);
+		} catch {
+			return {
+				storyKey,
+				tables: []
+			};
+		}
+	}
+	/**
+	* Compute row-level diffs between two Dolt revisions (branches or commit hashes)
+	* across all tracked tables.
+	*/
+	async _diffRange(fromRef, toRef, storyKey) {
+		const tableDiffs = [];
+		for (const table of DoltStateStore.DIFF_TABLES) try {
+			const rows = await this._client.query(`SELECT * FROM DOLT_DIFF('${fromRef}', '${toRef}', '${table}')`, [], "main");
+			if (rows.length === 0) continue;
+			const added = [];
+			const modified = [];
+			const deleted = [];
+			for (const row of rows) {
+				const diffType = row["diff_type"];
+				const rowKey = this._extractRowKey(row);
+				const before = this._extractPrefixedFields(row, "before_");
+				const after = this._extractPrefixedFields(row, "after_");
+				const diffRow = {
+					rowKey,
+					...before !== void 0 && { before },
+					...after !== void 0 && { after }
+				};
+				if (diffType === "added") added.push(diffRow);
+				else if (diffType === "modified") modified.push(diffRow);
+				else if (diffType === "removed") deleted.push(diffRow);
+			}
+			if (added.length > 0 || modified.length > 0 || deleted.length > 0) tableDiffs.push({
+				table,
+				added,
+				modified,
+				deleted
+			});
+		} catch {}
+		return {
+			storyKey,
+			tables: tableDiffs
+		};
+	}
+	/**
+	* Extract a human-readable row key from a DOLT_DIFF result row.
+	* Tries after_ fields first (for added/modified rows), then before_ fields
+	* (for removed rows). Skips commit_hash pseudo-columns.
+	*/
+	_extractRowKey(row) {
+		for (const prefix of ["after_", "before_"]) for (const [key, val] of Object.entries(row)) if (key.startsWith(prefix) && !key.endsWith("_commit_hash") && val !== null && val !== void 0) return String(val);
+		return "unknown";
+	}
+	/**
+	* Extract all fields with a given prefix from a DOLT_DIFF result row,
+	* stripping the prefix from the key names. Returns undefined if no matching
+	* fields are found.
+	*/
+	_extractPrefixedFields(row, prefix) {
+		const result = {};
+		for (const [key, val] of Object.entries(row)) if (key.startsWith(prefix)) result[key.slice(prefix.length)] = val;
+		return Object.keys(result).length > 0 ? result : void 0;
+	}
+	/** In-memory KV store for per-run arbitrary metrics. Not persisted to Dolt. */
+	_kvMetrics = new Map();
+	async setMetric(runId, key, value) {
+		let runMap = this._kvMetrics.get(runId);
+		if (runMap === void 0) {
+			runMap = new Map();
+			this._kvMetrics.set(runId, runMap);
+		}
+		runMap.set(key, value);
+	}
+	async getMetric(runId, key) {
+		return this._kvMetrics.get(runId)?.get(key);
+	}
+	async getHistory(limit) {
+		const effectiveLimit = limit ?? 20;
+		try {
+			const rows = await this._client.query(`SELECT commit_hash, date, message, committer FROM dolt_log LIMIT ?`, [effectiveLimit]);
+			const entries = [];
+			for (const row of rows) {
+				const hash = String(row.commit_hash ?? "");
+				const dateVal = row.date;
+				const timestamp = dateVal instanceof Date ? dateVal.toISOString() : String(dateVal ?? "");
+				const message = String(row.message ?? "");
+				const author = row.committer ? String(row.committer) : void 0;
+				const storyKeyMatch = /story\/([0-9]+-[0-9]+)/i.exec(message);
+				entries.push({
+					hash,
+					timestamp,
+					storyKey: storyKeyMatch ? storyKeyMatch[1] : null,
+					message,
+					author
+				});
+			}
+			return entries;
+		} catch (err) {
+			const detail = err instanceof Error ? err.message : String(err);
+			throw new DoltQueryError("getHistory", detail);
+		}
+	}
+};
+
+//#endregion
+//#region src/modules/state/index.ts
+const logger$1 = createLogger("state:factory");
+/**
+* Synchronously check whether Dolt is available and a Dolt repo exists at the
+* canonical state path under `basePath`.
+*
+* @param basePath - Project root to check (e.g. `process.cwd()`).
+* @returns `{ available: true, reason: '...' }` when both probes pass,
+*          `{ available: false, reason: '...' }` otherwise.
+*/
+function detectDoltAvailableSync(basePath) {
+	const result = spawnSync("dolt", ["version"], { stdio: "ignore" });
+	const binaryFound = result.error == null && result.status === 0;
+	if (!binaryFound) return {
+		available: false,
+		reason: "dolt binary not found on PATH"
+	};
+	const stateDoltDir = join$1(basePath, ".substrate", "state", ".dolt");
+	const repoExists = existsSync(stateDoltDir);
+	if (!repoExists) return {
+		available: false,
+		reason: `Dolt repo not initialised at ${stateDoltDir}`
+	};
+	return {
+		available: true,
+		reason: "dolt binary found and repo initialised"
+	};
+}
+/**
+* Create a StateStore backed by the specified backend.
+*
+* @param config - Optional configuration. Defaults to `{ backend: 'auto' }`.
+* @returns A StateStore instance. Call `initialize()` before use.
+*/
+function createStateStore(config = {}) {
+	const backend = config.backend ?? "auto";
+	if (backend === "dolt") {
+		const repoPath = config.basePath ?? process.cwd();
+		const client = new DoltClient({ repoPath });
+		return new DoltStateStore({
+			repoPath,
+			client
+		});
+	}
+	if (backend === "auto") {
+		const repoPath = config.basePath ?? process.cwd();
+		const detection = detectDoltAvailableSync(repoPath);
+		if (detection.available) {
+			logger$1.debug(`Dolt detected, using DoltStateStore (state path: ${join$1(repoPath, ".substrate", "state")})`);
+			const client = new DoltClient({ repoPath });
+			return new DoltStateStore({
+				repoPath,
+				client
+			});
+		} else {
+			logger$1.debug(`Dolt not found, using FileStateStore (reason: ${detection.reason})`);
+			return new FileStateStore({ basePath: config.basePath });
+		}
+	}
+	return new FileStateStore({ basePath: config.basePath });
+}
+
+//#endregion
+//#region src/cli/commands/health.ts
+const logger = createLogger("health-cmd");
+/** Default stall threshold in seconds — also used by supervisor default */
+const DEFAULT_STALL_THRESHOLD_SECONDS = 600;
+/**
+* Determine whether a ps output line represents the substrate pipeline orchestrator.
+* Handles invocation via:
+*   - `substrate run` (globally installed)
+*   - `substrate-ai run`
+*   - `node dist/cli/index.js run` (npm run substrate:dev)
+*   - `npx substrate run`
+*   - any node process whose command contains `run` with `--events` or `--stories`
+*
+* When `projectRoot` is provided, additionally checks that the command line
+* contains that path (via `--project-root` flag or as part of the binary/CWD path).
+* This ensures multi-project environments match the correct orchestrator.
+*/
+function isOrchestratorProcessLine(line, projectRoot) {
+	if (line.includes("grep")) return false;
+	let isOrchestrator = false;
+	if (line.includes("substrate run")) isOrchestrator = true;
+	else if (line.includes("substrate-ai run")) isOrchestrator = true;
+	else if (line.includes("index.js run")) isOrchestrator = true;
+	else if (line.includes("node") && /\srun(\s|$)/.test(line) && (line.includes("substrate") || line.includes("--events") || line.includes("--stories"))) isOrchestrator = true;
+	if (!isOrchestrator) return false;
+	if (projectRoot !== void 0) return line.includes(projectRoot);
+	return true;
+}
+function inspectProcessTree(opts) {
+	const { projectRoot, substrateDirPath, execFileSync: execFileSyncOverride, readFileSync: readFileSyncOverride } = opts ?? {};
+	const result = {
+		orchestrator_pid: null,
+		child_pids: [],
+		zombies: []
+	};
+	try {
+		let psOutput;
+		if (execFileSyncOverride !== void 0) psOutput = execFileSyncOverride("ps", ["-eo", "pid,ppid,stat,command"], {
+			encoding: "utf-8",
+			timeout: 5e3
+		});
+		else {
+			const { execFileSync: execFileSync$1 } = __require("node:child_process");
+			psOutput = execFileSync$1("ps", ["-eo", "pid,ppid,stat,command"], {
+				encoding: "utf-8",
+				timeout: 5e3
+			});
+		}
+		const lines = psOutput.split("\n");
+		if (substrateDirPath !== void 0) try {
+			const readFileSyncFn = readFileSyncOverride ?? ((path$1, encoding) => readFileSync(path$1, encoding));
+			const pidContent = readFileSyncFn(join(substrateDirPath, "orchestrator.pid"), "utf-8");
+			const pid = parseInt(pidContent.trim(), 10);
+			if (!isNaN(pid) && pid > 0) {
+				const isAlive = lines.some((line) => {
+					const parts = line.trim().split(/\s+/);
+					if (parts.length < 3) return false;
+					return parseInt(parts[0], 10) === pid && !parts[2].includes("Z");
+				});
+				if (isAlive) result.orchestrator_pid = pid;
+				else result.pid_file_dead = true;
+			}
+		} catch {}
+		if (result.orchestrator_pid === null) {
+			for (const line of lines) if (isOrchestratorProcessLine(line, projectRoot)) {
+				const match = line.trim().match(/^(\d+)/);
+				if (match) {
+					result.orchestrator_pid = parseInt(match[1], 10);
+					break;
+				}
+			}
+		}
+		if (result.orchestrator_pid !== null) for (const line of lines) {
+			const parts = line.trim().split(/\s+/);
+			if (parts.length >= 3) {
+				const pid = parseInt(parts[0], 10);
+				const ppid = parseInt(parts[1], 10);
+				const stat$1 = parts[2];
+				if (ppid === result.orchestrator_pid && pid !== result.orchestrator_pid) {
+					result.child_pids.push(pid);
+					if (stat$1.includes("Z")) result.zombies.push(pid);
+				}
+			}
+		}
+	} catch {}
+	return result;
+}
+/**
+* Collect all descendant PIDs of the given root PIDs by walking the process
+* tree recursively. This ensures that grandchildren of the orchestrator
+* (e.g. node subprocesses spawned by `claude -p`) are also killed during
+* stall recovery, leaving no orphan processes.
+*
+* Returns only the descendants — the root PIDs themselves are NOT included.
+*/
+function getAllDescendantPids(rootPids, execFileSyncOverride) {
+	if (rootPids.length === 0) return [];
+	try {
+		let psOutput;
+		if (execFileSyncOverride !== void 0) psOutput = execFileSyncOverride("ps", ["-eo", "pid,ppid"], {
+			encoding: "utf-8",
+			timeout: 5e3
+		});
+		else {
+			const { execFileSync: execFileSync$1 } = __require("node:child_process");
+			psOutput = execFileSync$1("ps", ["-eo", "pid,ppid"], {
+				encoding: "utf-8",
+				timeout: 5e3
+			});
+		}
+		const childrenOf = new Map();
+		for (const line of psOutput.split("\n")) {
+			const parts = line.trim().split(/\s+/);
+			if (parts.length >= 2) {
+				const pid = parseInt(parts[0], 10);
+				const ppid = parseInt(parts[1], 10);
+				if (!isNaN(pid) && !isNaN(ppid) && pid > 0) {
+					if (!childrenOf.has(ppid)) childrenOf.set(ppid, []);
+					childrenOf.get(ppid).push(pid);
+				}
+			}
+		}
+		const descendants = [];
+		const seen = new Set(rootPids);
+		const queue = [...rootPids];
+		while (queue.length > 0) {
+			const current = queue.shift();
+			const children = childrenOf.get(current) ?? [];
+			for (const child of children) if (!seen.has(child)) {
+				seen.add(child);
+				descendants.push(child);
+				queue.push(child);
+			}
+		}
+		return descendants;
+	} catch {
+		return [];
+	}
+}
+/**
+* Derive health story counts from manifest `per_story_state`.
+* Maps manifest status strings to health output buckets.
+*/
+function buildHealthStoryCountsFromManifest(perStoryState) {
+	const counts = {
+		active: 0,
+		completed: 0,
+		escalated: 0,
+		pending: 0,
+		failed: 0
+	};
+	for (const entry of Object.values(perStoryState)) switch (entry.status) {
+		case "complete":
+			counts.completed++;
+			break;
+		case "escalated":
+			counts.escalated++;
+			break;
+		case "failed":
+		case "verification-failed":
+			counts.failed++;
+			break;
+		case "pending":
+		case "gated":
+			counts.pending++;
+			break;
+		case "dispatched":
+		case "in-review":
+		case "recovered":
+		default:
+			counts.active++;
+			break;
+	}
+	return counts;
+}
+/**
+* Fetch pipeline health data as a structured object without any stdout side-effects.
+* Used by runSupervisorAction to poll health without formatting overhead.
+*
+* Returns a NO_PIPELINE_RUNNING health object for all graceful "no data" cases
+* (missing DB, missing run, terminal run status). Throws only on unexpected errors.
+*/
+async function getAutoHealthData(options) {
+	const { runId, projectRoot, stateStore, stateStoreConfig } = options;
+	const dbRoot = await resolveMainRepoRoot(projectRoot);
+	const dbPath = join(dbRoot, ".substrate", "substrate.db");
+	let doltStateInfo;
+	if (stateStoreConfig?.backend === "dolt" && stateStore) {
+		const repoPath = stateStoreConfig.basePath ?? projectRoot;
+		const doltDirPath = join(repoPath, ".dolt");
+		const initialized = existsSync(doltDirPath);
+		let responsive = false;
+		let version;
+		let branches;
+		let currentBranch;
+		try {
+			await stateStore.getHistory(1);
+			responsive = true;
+			try {
+				const { execFile: ef } = await import("node:child_process");
+				const { promisify: p } = await import("node:util");
+				const execFileAsync = p(ef);
+				const { stdout } = await execFileAsync("dolt", ["version"]);
+				const match = stdout.match(/dolt version (\S+)/);
+				if (match) version = match[1];
+			} catch {}
+			try {
+				const { execFile: ef } = await import("node:child_process");
+				const { promisify: p } = await import("node:util");
+				const execFileAsync = p(ef);
+				const { stdout } = await execFileAsync("dolt", ["branch", "--list"], { cwd: repoPath });
+				const lines = stdout.split("\n").filter((l) => l.trim().length > 0);
+				branches = lines.map((l) => {
+					const trimmed = l.trim();
+					if (trimmed.startsWith("* ")) {
+						currentBranch = trimmed.slice(2).trim();
+						return currentBranch;
+					}
+					return trimmed;
+				});
+			} catch {}
+		} catch {
+			responsive = false;
+		}
+		doltStateInfo = {
+			initialized,
+			responsive,
+			...version !== void 0 ? { version } : {},
+			...branches !== void 0 ? { branches } : {},
+			...currentBranch !== void 0 ? { current_branch: currentBranch } : {}
+		};
+	}
+	const NO_PIPELINE = {
+		verdict: "NO_PIPELINE_RUNNING",
+		run_id: null,
+		status: null,
+		current_phase: null,
+		staleness_seconds: 0,
+		last_activity: "",
+		process: {
+			orchestrator_pid: null,
+			child_pids: [],
+			zombies: []
+		},
+		stories: {
+			active: 0,
+			completed: 0,
+			escalated: 0,
+			details: {}
+		},
+		...doltStateInfo !== void 0 ? { dolt_state: doltStateInfo } : {}
+	};
+	const doltDir = join(dbRoot, ".substrate", "state", ".dolt");
+	if (!existsSync(dbPath) && !existsSync(doltDir)) return NO_PIPELINE;
+	const adapter = createDatabaseAdapter$1({
+		backend: "auto",
+		basePath: dbRoot
+	});
+	try {
+		await initSchema(adapter);
+		let run;
+		if (runId !== void 0) run = await getPipelineRunById(adapter, runId);
+		else {
+			let currentRunId;
+			try {
+				const currentRunIdPath = join(dbRoot, ".substrate", "current-run-id");
+				const content = readFileSync(currentRunIdPath, "utf-8").trim();
+				const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+				if (UUID_RE.test(content)) currentRunId = content;
+			} catch {}
+			if (currentRunId !== void 0) run = await getPipelineRunById(adapter, currentRunId);
+			if (run === void 0) run = await getLatestRun(adapter);
+		}
+		if (run === void 0) {
+			const substrateDirPath$1 = join(dbRoot, ".substrate");
+			const fallbackProcessInfo = inspectProcessTree({
+				projectRoot: dbRoot,
+				substrateDirPath: substrateDirPath$1
+			});
+			if (fallbackProcessInfo.orchestrator_pid !== null) return {
+				verdict: "HEALTHY",
+				run_id: null,
+				status: "running",
+				current_phase: "implementation",
+				staleness_seconds: 0,
+				last_activity: new Date().toISOString(),
+				process: fallbackProcessInfo,
+				stories: {
+					active: 0,
+					completed: 0,
+					escalated: 0,
+					details: {}
+				},
+				...doltStateInfo !== void 0 ? { dolt_state: doltStateInfo } : {}
+			};
+			return NO_PIPELINE;
+		}
+		const updatedAt = parseDbTimestampAsUtc(run.updated_at ?? "");
+		const stalenessSeconds = Math.round((Date.now() - updatedAt.getTime()) / 1e3);
+		let storyDetails = {};
+		let active = 0;
+		let completed = 0;
+		let escalated = 0;
+		let pending = 0;
+		try {
+			if (run.token_usage_json) {
+				const state = JSON.parse(run.token_usage_json);
+				if (state.stories) for (const [key, s] of Object.entries(state.stories)) {
+					storyDetails[key] = {
+						phase: s.phase,
+						review_cycles: s.reviewCycles
+					};
+					if (s.phase === "COMPLETE") completed++;
+					else if (s.phase === "ESCALATED") escalated++;
+					else if (s.phase === "PENDING") pending++;
+					else active++;
+				}
+			}
+		} catch {}
+		let manifestSupervisor;
+		let manifestStoryCounts;
+		try {
+			const { manifest: resolvedManifest } = await resolveRunManifest(dbRoot, run.id);
+			if (resolvedManifest !== null) {
+				const manifestData = await resolvedManifest.read();
+				manifestSupervisor = {
+					pid: manifestData.supervisor_pid,
+					session_id: manifestData.supervisor_session_id
+				};
+				manifestStoryCounts = buildHealthStoryCountsFromManifest(manifestData.per_story_state);
+				logger.debug({ runId: run.id }, "health: story counts and supervisor read from manifest");
+			}
+		} catch {
+			logger.debug({ runId: run.id }, "health: manifest read failed — using token_usage_json counts");
+		}
+		const finalActive = manifestStoryCounts?.active ?? active;
+		const finalCompleted = manifestStoryCounts?.completed ?? completed;
+		const finalEscalated = manifestStoryCounts?.escalated ?? escalated;
+		const finalPending = manifestStoryCounts?.pending ?? pending;
+		const finalFailed = manifestStoryCounts?.failed;
+		const substrateDirPath = join(dbRoot, ".substrate");
+		const processInfo = options._processInfoOverride ?? inspectProcessTree({
+			projectRoot,
+			substrateDirPath
+		});
+		let verdict = "NO_PIPELINE_RUNNING";
+		if (run.status === "running") if (processInfo.orchestrator_pid !== null) verdict = "HEALTHY";
+		else if (processInfo.pid_file_dead === true) verdict = "STALLED";
+		else if (processInfo.zombies.length > 0) verdict = "STALLED";
+		else if (stalenessSeconds > DEFAULT_STALL_THRESHOLD_SECONDS) verdict = "STALLED";
+		else if (finalActive > 0) verdict = "STALLED";
+		else verdict = "HEALTHY";
+		else if (run.status === "completed" || run.status === "failed" || run.status === "stopped") verdict = "NO_PIPELINE_RUNNING";
+		const warnings = [];
+		if (doltStateInfo !== void 0 && doltStateInfo.responsive === false) warnings.push("Dolt not connected — decision store queries may fail, story context will be degraded");
+		if (finalEscalated > 0) warnings.push(`${finalEscalated} story(ies) escalated — operator intervention may be needed`);
+		const healthOutput = {
+			verdict,
+			run_id: run.id,
+			status: run.status,
+			current_phase: run.current_phase ?? null,
+			staleness_seconds: stalenessSeconds,
+			last_activity: run.updated_at ?? "",
+			process: processInfo,
+			stories: {
+				active: finalActive,
+				completed: finalCompleted,
+				escalated: finalEscalated,
+				pending: finalPending,
+				...finalFailed !== void 0 ? { failed: finalFailed } : {},
+				details: storyDetails
+			},
+			...manifestSupervisor !== void 0 ? { manifest_supervisor: manifestSupervisor } : {},
+			...doltStateInfo !== void 0 ? { dolt_state: doltStateInfo } : {},
+			...warnings.length > 0 ? { warnings } : {}
+		};
+		return healthOutput;
+	} finally {
+		try {
+			await adapter.close();
+		} catch {}
+	}
+}
+async function runHealthAction(options) {
+	const { outputFormat } = options;
+	try {
+		const health = await getAutoHealthData(options);
+		if (outputFormat === "json") process.stdout.write(formatOutput(health, "json", true) + "\n");
+		else {
+			const verdictLabel = health.verdict === "HEALTHY" ? "HEALTHY" : health.verdict === "STALLED" ? "STALLED" : "NO PIPELINE RUNNING";
+			process.stdout.write(`\nPipeline Health: ${verdictLabel}\n`);
+			if (health.run_id !== null) {
+				process.stdout.write(`  Run:          ${health.run_id}\n`);
+				process.stdout.write(`  Status:       ${health.status}\n`);
+				process.stdout.write(`  Phase:        ${health.current_phase ?? "N/A"}\n`);
+				process.stdout.write(`  Last Active:  ${health.last_activity} (${health.staleness_seconds}s ago)\n`);
+				const processInfo = health.process;
+				if (processInfo.orchestrator_pid !== null) {
+					process.stdout.write(`  Orchestrator: PID ${processInfo.orchestrator_pid}\n`);
+					process.stdout.write(`  Children:     ${processInfo.child_pids.length} active`);
+					if (processInfo.zombies.length > 0) process.stdout.write(` (${processInfo.zombies.length} ZOMBIE)`);
+					process.stdout.write("\n");
+				} else process.stdout.write("  Orchestrator: not running\n");
+				const storyDetails = health.stories.details;
+				if (Object.keys(storyDetails).length > 0) {
+					process.stdout.write("\n  Stories:\n");
+					for (const [key, s] of Object.entries(storyDetails)) process.stdout.write(`    ${key}: ${s.phase} (${s.review_cycles} review cycles)\n`);
+					process.stdout.write(`\n  Summary: ${health.stories.active} active, ${health.stories.completed} completed, ${health.stories.escalated} escalated\n`);
+				}
+			}
+			if (health.verdict === "STALLED") {
+				process.stdout.write("\n  Recommended Actions:\n");
+				if (health.process.orchestrator_pid !== null) process.stdout.write(`    1. Kill stalled orchestrator: kill ${health.process.orchestrator_pid}\n`);
+				if (health.process.zombies.length > 0) process.stdout.write(`    ${health.process.orchestrator_pid !== null ? "2" : "1"}. Kill zombie processes: kill ${health.process.zombies.join(" ")}\n`);
+				process.stdout.write(`    ${health.process.orchestrator_pid !== null ? "3" : "2"}. Resume the run: substrate resume\n`);
+				process.stdout.write(`    ${health.process.orchestrator_pid !== null ? "4" : "3"}. Or start fresh: substrate run --events --stories <keys>\n`);
+			} else if (health.verdict === "NO_PIPELINE_RUNNING" && health.stories.escalated > 0) {
+				process.stdout.write("\n  Recommended Actions:\n");
+				process.stdout.write("    1. Retry escalated stories: substrate retry-escalated\n");
+				process.stdout.write("    2. Or start a new run: substrate run --events\n");
+			}
+			if (health.warnings !== void 0 && health.warnings.length > 0) {
+				process.stdout.write("\n  Warnings:\n");
+				for (const w of health.warnings) process.stdout.write(`    ⚠ ${w}\n`);
+			}
+			if (health.dolt_state !== void 0) {
+				const ds = health.dolt_state;
+				const initStr = ds.initialized ? "yes" : "no";
+				const respStr = ds.responsive ? "yes" : "no";
+				const verStr = ds.version !== void 0 ? ` (v${ds.version})` : "";
+				process.stdout.write(`\n  Dolt State:   initialized=${initStr} responsive=${respStr}${verStr}\n`);
+			}
+		}
+		return 0;
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		if (outputFormat === "json") process.stdout.write(formatOutput(null, "json", false, msg) + "\n");
+		else process.stderr.write(`Error: ${msg}\n`);
+		logger.error({ err }, "health action failed");
+		return 1;
+	}
+}
+function registerHealthCommand(program, _version = "0.0.0", projectRoot = process.cwd()) {
+	program.command("health").description("Check pipeline health: process status, stall detection, and verdict").option("--run-id <id>", "Pipeline run ID to query (defaults to latest)").option("--project-root <path>", "Project root directory", projectRoot).option("--output-format <format>", "Output format: human (default) or json", "human").action(async (opts) => {
+		const outputFormat = opts.outputFormat === "json" ? "json" : "human";
+		const root = opts.projectRoot;
+		let stateStore;
+		let stateStoreConfig;
+		const doltStatePath = join(root, ".substrate", "state", ".dolt");
+		if (existsSync(doltStatePath)) {
+			const basePath = join(root, ".substrate", "state");
+			stateStoreConfig = {
+				backend: "dolt",
+				basePath
+			};
+			try {
+				stateStore = createStateStore({
+					backend: "dolt",
+					basePath
+				});
+				await stateStore.initialize();
+			} catch {
+				stateStore = void 0;
+				stateStoreConfig = void 0;
+			}
+		}
+		try {
+			const exitCode = await runHealthAction({
+				outputFormat,
+				runId: opts.runId,
+				projectRoot: root,
+				stateStore,
+				stateStoreConfig
+			});
+			process.exitCode = exitCode;
+		} finally {
+			try {
+				await stateStore?.close();
+			} catch {}
+		}
+	});
+}
+
+//#endregion
+export { BMAD_BASELINE_TOKENS_FULL, DEFAULT_STALL_THRESHOLD_SECONDS, DoltMergeConflict, FileStateStore, STOP_AFTER_VALID_PHASES, STORY_KEY_PATTERN$1 as STORY_KEY_PATTERN, SUBSTRATE_OWNED_SETTINGS_KEYS, VALID_PHASES, __commonJS, __require, __toESM, buildPipelineStatusOutput, createDatabaseAdapter$1 as createDatabaseAdapter, createStateStore, findPackageRoot, formatOutput, formatPipelineStatusHuman, formatPipelineSummary, formatTokenTelemetry, getAllDescendantPids, getAutoHealthData, getSubstrateDefaultSettings, inspectProcessTree, isOrchestratorProcessLine, parseDbTimestampAsUtc, registerHealthCommand, resolveBmadMethodSrcPath, resolveBmadMethodVersion, runHealthAction, validateStoryKey };
+//# sourceMappingURL=health-DC3y-sR6.js.map