substrate-ai 0.1.28 → 0.1.30

package/dist/cli/index.js

@@ -8362,16 +8362,40 @@ function getTokenUsageSummary(db, runId) {
 //#region src/persistence/queries/metrics.ts
 /**
 * Write or update run-level metrics.
+*
+* Uses INSERT ... ON CONFLICT DO UPDATE to avoid a TOCTOU race on the
+* `restarts` counter: when a row already exists, `restarts` is preserved from
+* the DB (so any `incrementRunRestarts()` calls made by the supervisor between
+* the caller's read and this write are not silently overwritten).
 */
 function writeRunMetrics(db, input) {
 	const stmt = db.prepare(`
-    INSERT OR REPLACE INTO run_metrics (
+    INSERT INTO run_metrics (
       run_id, methodology, status, started_at, completed_at,
       wall_clock_seconds, total_input_tokens, total_output_tokens, total_cost_usd,
       stories_attempted, stories_succeeded, stories_failed, stories_escalated,
       total_review_cycles, total_dispatches, concurrency_setting, max_concurrent_actual, restarts,
       is_baseline
     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(run_id) DO UPDATE SET
+      methodology = excluded.methodology,
+      status = excluded.status,
+      started_at = excluded.started_at,
+      completed_at = excluded.completed_at,
+      wall_clock_seconds = excluded.wall_clock_seconds,
+      total_input_tokens = excluded.total_input_tokens,
+      total_output_tokens = excluded.total_output_tokens,
+      total_cost_usd = excluded.total_cost_usd,
+      stories_attempted = excluded.stories_attempted,
+      stories_succeeded = excluded.stories_succeeded,
+      stories_failed = excluded.stories_failed,
+      stories_escalated = excluded.stories_escalated,
+      total_review_cycles = excluded.total_review_cycles,
+      total_dispatches = excluded.total_dispatches,
+      concurrency_setting = excluded.concurrency_setting,
+      max_concurrent_actual = excluded.max_concurrent_actual,
+      restarts = run_metrics.restarts,
+      is_baseline = run_metrics.is_baseline
   `);
 	stmt.run(input.run_id, input.methodology, input.status, input.started_at, input.completed_at ?? null, input.wall_clock_seconds ?? 0, input.total_input_tokens ?? 0, input.total_output_tokens ?? 0, input.total_cost_usd ?? 0, input.stories_attempted ?? 0, input.stories_succeeded ?? 0, input.stories_failed ?? 0, input.stories_escalated ?? 0, input.total_review_cycles ?? 0, input.total_dispatches ?? 0, input.concurrency_setting ?? 1, input.max_concurrent_actual ?? 1, input.restarts ?? 0, input.is_baseline ?? 0);
 }
@@ -8397,6 +8421,26 @@ function tagRunAsBaseline(db, runId) {
 	})();
 }
 /**
+* Get the current baseline run metrics (if any).
+*/
+function getBaselineRunMetrics(db) {
+	return db.prepare("SELECT * FROM run_metrics WHERE is_baseline = 1 LIMIT 1").get();
+}
+/**
+* Increment the restart count for a run by 1.
+* Called by the supervisor each time it successfully restarts the pipeline.
+* If the run_id does not yet exist in run_metrics, a placeholder row is
+* inserted so the restart count is not lost — writeRunMetrics will overwrite
+* all other fields when the run reaches a terminal state.
+*/
+function incrementRunRestarts(db, runId) {
+	db.prepare(`
+    INSERT INTO run_metrics (run_id, methodology, status, started_at, restarts)
+    VALUES (?, 'unknown', 'running', datetime('now'), 1)
+    ON CONFLICT(run_id) DO UPDATE SET restarts = run_metrics.restarts + 1
+  `).run(runId);
+}
+/**
 * Write or update story-level metrics.
 */
 function writeStoryMetrics(db, input) {
@@ -8435,7 +8479,7 @@ function compareRunMetrics(db, runIdA, runIdB) {
 	const a = getRunMetrics(db, runIdA);
 	const b = getRunMetrics(db, runIdB);
 	if (!a || !b) return null;
-	const pct = (base, diff) => base === 0 ? 0 : Math.round(diff / base * 100 * 10) / 10;
+	const pct = (base, diff) => base === 0 ? null : Math.round(diff / base * 100 * 10) / 10;
 	const inputDelta = b.total_input_tokens - a.total_input_tokens;
 	const outputDelta = b.total_output_tokens - a.total_output_tokens;
 	const clockDelta = (b.wall_clock_seconds ?? 0) - (a.wall_clock_seconds ?? 0);
@@ -10478,6 +10522,7 @@ function createImplementationOrchestrator(deps) {
 	const _phaseStartMs = new Map();
 	const _phaseEndMs = new Map();
 	const _storyDispatches = new Map();
+	let _maxConcurrentActual = 0;
 	function startPhase(storyKey, phase) {
 		if (!_phaseStartMs.has(storyKey)) _phaseStartMs.set(storyKey, new Map());
 		_phaseStartMs.get(storyKey).set(phase, Date.now());
@@ -10494,9 +10539,14 @@ function createImplementationOrchestrator(deps) {
 		const ends = _phaseEndMs.get(storyKey);
 		if (!starts || starts.size === 0) return "{}";
 		const durations = {};
+		const nowMs = Date.now();
 		for (const [phase, startMs] of starts) {
-			const endMs = ends?.get(phase) ?? Date.now();
-			durations[phase] = Math.round((endMs - startMs) / 1e3);
+			const endMs = ends?.get(phase);
+			if (endMs === void 0) logger$36.warn({
+				storyKey,
+				phase
+			}, "Phase has no end time — story may have errored mid-phase. Duration capped to now() and may be inflated.");
+			durations[phase] = Math.round(((endMs ?? nowMs) - startMs) / 1e3);
 		}
 		return JSON.stringify(durations);
 	}
@@ -10542,6 +10592,7 @@ function createImplementationOrchestrator(deps) {
 			if (_startedAt !== void 0) status.totalDurationMs = new Date(_completedAt).getTime() - new Date(_startedAt).getTime();
 		}
 		if (_decomposition !== void 0) status.decomposition = { ..._decomposition };
+		if (_maxConcurrentActual > 0) status.maxConcurrentActual = _maxConcurrentActual;
 		return status;
 	}
 	function updateStory(storyKey, updates) {
@@ -11322,6 +11373,7 @@ function createImplementationOrchestrator(deps) {
 				if (idx !== -1) running.splice(idx, 1);
 			});
 			running.push(p);
+			if (running.length > _maxConcurrentActual) _maxConcurrentActual = running.length;
 		}
 		const initial = Math.min(maxConcurrency, queue.length);
 		for (let i = 0; i < initial; i++) enqueue();
@@ -16156,6 +16208,108 @@ async function scaffoldClaudeSettings(projectRoot) {
 	await writeFile(settingsPath, JSON.stringify(merged, null, 2) + "\n", "utf8");
 	logger$3.info({ settingsPath }, "Wrote substrate settings to .claude/settings.json");
 }
+/**
+* Resolve the absolute path to bmad-method's installer lib directory.
+* Returns null if bmad-method is not installed.
+*/
+function resolveBmadMethodInstallerLibPath(fromDir = __dirname) {
+	try {
+		const _require = createRequire$1(join(fromDir, "synthetic.js"));
+		const pkgJsonPath = _require.resolve("bmad-method/package.json");
+		return join(dirname(pkgJsonPath), "tools", "cli", "installers", "lib");
+	} catch {
+		return null;
+	}
+}
+/**
+* Scan the _bmad/ directory for installed module names (excluding 'core' and '_config').
+* Returns module names that contain agents/, workflows/, or tasks/ subdirs.
+*/
+function scanBmadModules(bmadDir) {
+	const modules = [];
+	try {
+		const entries = readdirSync(bmadDir, { withFileTypes: true });
+		for (const entry of entries) {
+			if (!entry.isDirectory() || entry.name.startsWith(".") || entry.name.startsWith("_") || entry.name === "core") continue;
+			const modPath = join(bmadDir, entry.name);
+			const hasAgents = existsSync(join(modPath, "agents"));
+			const hasWorkflows = existsSync(join(modPath, "workflows"));
+			const hasTasks = existsSync(join(modPath, "tasks"));
+			if (hasAgents || hasWorkflows || hasTasks) modules.push(entry.name);
+		}
+	} catch {}
+	return modules;
+}
+/**
+* Remove existing bmad-*.md files from .claude/commands/ for idempotent regeneration.
+* Preserves user's custom (non-bmad) command files.
+*/
+function clearBmadCommandFiles(commandsDir) {
+	try {
+		const entries = readdirSync(commandsDir);
+		for (const entry of entries) if (entry.startsWith("bmad-") && entry.endsWith(".md")) try {
+			unlinkSync(join(commandsDir, entry));
+		} catch {}
+	} catch {}
+}
+/**
+* Generate .claude/commands/ files by calling bmad-method's command generators.
+*
+* Uses the installed bmad-method package's AgentCommandGenerator,
+* WorkflowCommandGenerator, and TaskToolCommandGenerator classes via createRequire.
+* Generates CSV manifests first so workflow/task generators can discover content.
+*
+* Graceful degradation: warns but never fails init.
+*/
+async function scaffoldClaudeCommands(projectRoot, outputFormat) {
+	const bmadDir = join(projectRoot, "_bmad");
+	if (!existsSync(bmadDir)) return;
+	const installerLibPath = resolveBmadMethodInstallerLibPath();
+	if (!installerLibPath) {
+		if (outputFormat !== "json") process.stderr.write("Warning: bmad-method not found. Skipping .claude/commands/ generation.\n");
+		return;
+	}
+	try {
+		const _require = createRequire$1(join(__dirname, "synthetic.js"));
+		const { AgentCommandGenerator } = _require(join(installerLibPath, "ide", "shared", "agent-command-generator.js"));
+		const { WorkflowCommandGenerator } = _require(join(installerLibPath, "ide", "shared", "workflow-command-generator.js"));
+		const { TaskToolCommandGenerator } = _require(join(installerLibPath, "ide", "shared", "task-tool-command-generator.js"));
+		const { ManifestGenerator } = _require(join(installerLibPath, "core", "manifest-generator.js"));
+		const nonCoreModules = scanBmadModules(bmadDir);
+		const allModules = ["core", ...nonCoreModules];
+		try {
+			const manifestGen = new ManifestGenerator();
+			await manifestGen.generateManifests(bmadDir, allModules, [], { ides: ["claude-code"] });
+		} catch (manifestErr) {
+			logger$3.warn({ err: manifestErr }, "ManifestGenerator failed; workflow/task commands may be incomplete");
+		}
+		const commandsDir = join(projectRoot, ".claude", "commands");
+		mkdirSync(commandsDir, { recursive: true });
+		clearBmadCommandFiles(commandsDir);
+		const agentGen = new AgentCommandGenerator("_bmad");
+		const { artifacts: agentArtifacts } = await agentGen.collectAgentArtifacts(bmadDir, nonCoreModules);
+		const agentCount = await agentGen.writeDashArtifacts(commandsDir, agentArtifacts);
+		const workflowGen = new WorkflowCommandGenerator("_bmad");
+		const { artifacts: workflowArtifacts } = await workflowGen.collectWorkflowArtifacts(bmadDir);
+		const workflowCount = await workflowGen.writeDashArtifacts(commandsDir, workflowArtifacts);
+		const taskToolGen = new TaskToolCommandGenerator("_bmad");
+		const { artifacts: taskToolArtifacts } = await taskToolGen.collectTaskToolArtifacts(bmadDir);
+		const taskToolCount = await taskToolGen.writeDashArtifacts(commandsDir, taskToolArtifacts);
+		const total = agentCount + workflowCount + taskToolCount;
+		if (outputFormat !== "json") process.stdout.write(`Generated ${String(total)} Claude Code commands (${String(agentCount)} agents, ${String(workflowCount)} workflows, ${String(taskToolCount)} tasks/tools)\n`);
+		logger$3.info({
+			agentCount,
+			workflowCount,
+			taskToolCount,
+			total,
+			commandsDir
+		}, "Generated .claude/commands/");
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		if (outputFormat !== "json") process.stderr.write(`Warning: .claude/commands/ generation failed: ${msg}\n`);
+		logger$3.warn({ err }, "scaffoldClaudeCommands failed; init continues");
+	}
+}
 async function runAutoInit(options) {
 	const { pack: packName, projectRoot, outputFormat, force = false } = options;
 	const packPath = join(projectRoot, "packs", packName);
@@ -16206,6 +16360,7 @@ async function runAutoInit(options) {
 		await scaffoldClaudeMd(projectRoot);
 		await scaffoldStatuslineScript(projectRoot);
 		await scaffoldClaudeSettings(projectRoot);
+		await scaffoldClaudeCommands(projectRoot, outputFormat);
 		const successMsg = `Pack '${packName}' and database initialized successfully at ${dbPath}`;
 		if (outputFormat === "json") process.stdout.write(formatOutput({
 			pack: packName,
@@ -16676,7 +16831,8 @@ async function runAutoRun(options) {
 				stories_escalated: escalatedKeys.length,
 				total_review_cycles: totalReviewCycles,
 				total_dispatches: totalDispatches,
-				concurrency_setting: concurrency
+				concurrency_setting: concurrency,
+				max_concurrent_actual: status.maxConcurrentActual ?? Math.min(concurrency, storyKeys.length)
 			});
 		} catch (metricsErr) {
 			logger$3.warn({ err: metricsErr }, "Failed to write run metrics (best-effort)");
@@ -17665,7 +17821,51 @@ function defaultSupervisorDeps() {
 			process.kill(pid, signal);
 		},
 		resumePipeline: runAutoResume,
-		sleep: (ms) => new Promise((resolve$2) => setTimeout(resolve$2, ms))
+		sleep: (ms) => new Promise((resolve$2) => setTimeout(resolve$2, ms)),
+		incrementRestarts: (() => {
+			let cachedDbWrapper = null;
+			return (runId, projectRoot) => {
+				try {
+					if (cachedDbWrapper === null) {
+						const dbDir = join(projectRoot, ".substrate");
+						const dbPath = join(dbDir, "substrate.db");
+						cachedDbWrapper = new DatabaseWrapper(dbPath);
+					}
+					incrementRunRestarts(cachedDbWrapper.getDb(), runId);
+				} catch {
+					try {
+						cachedDbWrapper?.close();
+					} catch {}
+					cachedDbWrapper = null;
+				}
+			};
+		})(),
+		runAnalysis: async (runId, projectRoot) => {
+			const dbPath = join(projectRoot, ".substrate", "substrate.db");
+			if (!existsSync(dbPath)) return;
+			const dbWrapper = new DatabaseWrapper(dbPath);
+			try {
+				dbWrapper.open();
+				runMigrations(dbWrapper.db);
+				const db = dbWrapper.db;
+				const run = getRunMetrics(db, runId);
+				if (!run) return;
+				const stories = getStoryMetricsForRun(db, runId);
+				const baseline = getBaselineRunMetrics(db);
+				const baselineStories = baseline && baseline.run_id !== runId ? getStoryMetricsForRun(db, baseline.run_id) : [];
+				const analysisPath = "../../modules/supervisor/analysis.js";
+				const { generateAnalysisReport, writeAnalysisReport } = await import(
+					/* @vite-ignore */
+					analysisPath
+);
+				const report = generateAnalysisReport(run, stories, baseline, baselineStories);
+				writeAnalysisReport(report, projectRoot);
+			} catch {} finally {
+				try {
+					dbWrapper.close();
+				} catch {}
+			}
+		}
 	};
 }
 /**
@@ -17680,8 +17880,8 @@ function defaultSupervisorDeps() {
 *   2 — max restarts exceeded (safety valve triggered)
 */
 async function runAutoSupervisor(options, deps = {}) {
-	const { pollInterval, stallThreshold, maxRestarts, outputFormat, projectRoot, runId, pack } = options;
-	const { getHealth, killPid, resumePipeline, sleep } = {
+	const { pollInterval, stallThreshold, maxRestarts, outputFormat, projectRoot, runId, pack, experiment } = options;
+	const { getHealth, killPid, resumePipeline, sleep, incrementRestarts, runAnalysis } = {
 		...defaultSupervisorDeps(),
 		...deps
 	};
@@ -17721,6 +17921,52 @@ async function runAutoSupervisor(options, deps = {}) {
 				restarts: restartCount
 			});
 			log(`\nPipeline reached terminal state. Elapsed: ${elapsedSeconds}s | succeeded: ${succeeded.length} | failed: ${failed.length} | restarts: ${restartCount}`);
+			if (health.run_id !== null && runAnalysis !== void 0) {
+				log(`[supervisor] Running post-run analysis for ${health.run_id}...`);
+				await runAnalysis(health.run_id, projectRoot);
+				log(`[supervisor] Analysis report written to _bmad-output/supervisor-reports/${health.run_id}-analysis.md`);
+				emitEvent$1({
+					type: "supervisor:analysis:complete",
+					run_id: health.run_id
+				});
+			}
+			if (experiment && health.run_id !== null) {
+				log(`\n[supervisor] Experiment mode enabled. Checking for optimization recommendations...`);
+				emitEvent$1({
+					type: "supervisor:experiment:start",
+					run_id: health.run_id
+				});
+				const analysisReportPath = join(projectRoot, "_bmad-output", "supervisor-reports", `${health.run_id}-analysis.json`);
+				try {
+					const { readFile: fsReadFile } = await import("fs/promises");
+					const raw = await fsReadFile(analysisReportPath, "utf-8");
+					const analysisData = JSON.parse(raw);
+					const recommendations = analysisData.recommendations ?? [];
+					if (recommendations.length === 0) {
+						log(`[supervisor] No recommendations found in analysis report — skipping experiments.`);
+						emitEvent$1({
+							type: "supervisor:experiment:skip",
+							run_id: health.run_id,
+							reason: "no_recommendations"
+						});
+					} else {
+						log(`[supervisor] Found ${recommendations.length} recommendation(s) to experiment with.`);
+						emitEvent$1({
+							type: "supervisor:experiment:recommendations",
+							run_id: health.run_id,
+							count: recommendations.length
+						});
+					}
+				} catch {
+					log(`[supervisor] Analysis report not found at ${analysisReportPath} — skipping experiments.`);
+					log(`[supervisor] Run 'substrate auto metrics --analysis <run-id>' first to generate recommendations.`);
+					emitEvent$1({
+						type: "supervisor:experiment:skip",
+						run_id: health.run_id,
+						reason: "no_analysis_report"
+					});
+				}
+			}
 			return failed.length > 0 || escalated.length > 0 ? 1 : 0;
 		}
 		if (health.staleness_seconds >= stallThreshold) {
@@ -17767,6 +18013,7 @@ async function runAutoSupervisor(options, deps = {}) {
 				return 2;
 			}
 			restartCount++;
+			if (health.run_id !== null) incrementRestarts(health.run_id, projectRoot);
 			emitEvent$1({
 				type: "supervisor:restart",
 				run_id: health.run_id,
@@ -18129,12 +18376,13 @@ async function runAutoMetrics(options) {
 			if (outputFormat === "json") process.stdout.write(formatOutput(delta, "json", true) + "\n");
 			else {
 				const sign = (n) => n > 0 ? "+" : "";
+				const fmtPct = (pct) => pct === null ? "N/A" : `${sign(pct)}${pct}%`;
 				process.stdout.write(`\nMetrics Comparison: ${idA.slice(0, 8)} vs ${idB.slice(0, 8)}\n`);
-				process.stdout.write(`  Input tokens:   ${sign(delta.token_input_delta)}${delta.token_input_delta.toLocaleString()} (${sign(delta.token_input_pct)}${delta.token_input_pct}%)\n`);
-				process.stdout.write(`  Output tokens:  ${sign(delta.token_output_delta)}${delta.token_output_delta.toLocaleString()} (${sign(delta.token_output_pct)}${delta.token_output_pct}%)\n`);
-				process.stdout.write(`  Wall clock:     ${sign(delta.wall_clock_delta_seconds)}${delta.wall_clock_delta_seconds}s (${sign(delta.wall_clock_pct)}${delta.wall_clock_pct}%)\n`);
-				process.stdout.write(`  Review cycles:  ${sign(delta.review_cycles_delta)}${delta.review_cycles_delta} (${sign(delta.review_cycles_pct)}${delta.review_cycles_pct}%)\n`);
-				process.stdout.write(`  Cost USD:       ${sign(delta.cost_delta)}$${Math.abs(delta.cost_delta).toFixed(4)} (${sign(delta.cost_pct)}${delta.cost_pct}%)\n`);
+				process.stdout.write(`  Input tokens:   ${sign(delta.token_input_delta)}${delta.token_input_delta.toLocaleString()} (${fmtPct(delta.token_input_pct)})\n`);
+				process.stdout.write(`  Output tokens:  ${sign(delta.token_output_delta)}${delta.token_output_delta.toLocaleString()} (${fmtPct(delta.token_output_pct)})\n`);
+				process.stdout.write(`  Wall clock:     ${sign(delta.wall_clock_delta_seconds)}${delta.wall_clock_delta_seconds}s (${fmtPct(delta.wall_clock_pct)})\n`);
+				process.stdout.write(`  Review cycles:  ${sign(delta.review_cycles_delta)}${delta.review_cycles_delta} (${fmtPct(delta.review_cycles_pct)})\n`);
+				process.stdout.write(`  Cost USD:       ${delta.cost_delta < 0 ? "-" : sign(delta.cost_delta)}$${Math.abs(delta.cost_delta).toFixed(4)} (${fmtPct(delta.cost_pct)})\n`);
 			}
 			return 0;
 		}
@@ -18256,7 +18504,7 @@ function registerAutoCommand(program, _version = "0.0.0", projectRoot = process.
 		});
 		process.exitCode = exitCode;
 	});
-	auto.command("supervisor").description("Monitor a pipeline run and automatically recover from stalls").option("--poll-interval <seconds>", "Health poll interval in seconds", (v) => parseInt(v, 10), 60).option("--stall-threshold <seconds>", "Staleness in seconds before killing a stalled pipeline", (v) => parseInt(v, 10), 600).option("--max-restarts <n>", "Maximum automatic restarts before aborting", (v) => parseInt(v, 10), 3).option("--run-id <id>", "Pipeline run ID to monitor (defaults to latest)").option("--pack <name>", "Methodology pack name", "bmad").option("--project-root <path>", "Project root directory", projectRoot).option("--output-format <format>", "Output format: human (default) or json", "human").action(async (opts) => {
+	auto.command("supervisor").description("Monitor a pipeline run and automatically recover from stalls").option("--poll-interval <seconds>", "Health poll interval in seconds", (v) => parseInt(v, 10), 60).option("--stall-threshold <seconds>", "Staleness in seconds before killing a stalled pipeline", (v) => parseInt(v, 10), 600).option("--max-restarts <n>", "Maximum automatic restarts before aborting", (v) => parseInt(v, 10), 3).option("--run-id <id>", "Pipeline run ID to monitor (defaults to latest)").option("--pack <name>", "Methodology pack name", "bmad").option("--project-root <path>", "Project root directory", projectRoot).option("--output-format <format>", "Output format: human (default) or json", "human").option("--experiment", "After post-run analysis, enter experiment mode: create branches, apply modifications, run single-story experiments, and report verdicts (Story 17-4)", false).action(async (opts) => {
 		const outputFormat = opts.outputFormat === "json" ? "json" : "human";
 		const exitCode = await runAutoSupervisor({
 			pollInterval: opts.pollInterval,
@@ -18265,7 +18513,8 @@ function registerAutoCommand(program, _version = "0.0.0", projectRoot = process.
 			runId: opts.runId,
 			pack: opts.pack,
 			outputFormat,
-			projectRoot: opts.projectRoot
+			projectRoot: opts.projectRoot,
+			experiment: opts.experiment
 		});
 		process.exitCode = exitCode;
 	});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "substrate-ai",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "description": "Substrate — multi-agent orchestration daemon for AI coding agents",
   "type": "module",
   "license": "MIT",