substrate-ai 0.2.4 → 0.2.6

package/README.md

@@ -229,6 +229,15 @@ These commands are invoked by AI agents (Claude Code, Codex, Gemini CLI) during
 | `substrate monitor recommendations` | Display routing recommendations from performance data |
 | `substrate cost` | View cost and token usage summary |
 
+### Export & Sharing
+
+| Command | Description |
+|---------|-------------|
+| `substrate export` | Export planning artifacts (product brief, PRD, architecture, epics) as markdown |
+| `substrate export --run-id <id>` | Export artifacts from a specific pipeline run |
+| `substrate export --output-dir <dir>` | Write to a custom directory (default: `_bmad-output/planning-artifacts/`) |
+| `substrate export --output-format json` | Emit JSON result to stdout for agent consumption |
+
 ### Worktree Management
 
 | Command | Description |

package/dist/cli/index.js

@@ -2,10 +2,10 @@
 import { createLogger, deepMask } from "../logger-C6n1g8uP.js";
 import { AdapterRegistry, createEventBus } from "../event-bus-J-bw-pkp.js";
 import { CURRENT_CONFIG_FORMAT_VERSION, CURRENT_TASK_GRAPH_VERSION, PartialSubstrateConfigSchema, SUPPORTED_CONFIG_FORMAT_VERSIONS, SubstrateConfigSchema, defaultConfigMigrator } from "../version-manager-impl-BpVx2DkY.js";
-import { DatabaseWrapper, SUBSTRATE_OWNED_SETTINGS_KEYS, VALID_PHASES, buildPipelineStatusOutput, createContextCompiler, createDispatcher, createImplementationOrchestrator, createPackLoader, createPhaseOrchestrator, createStopAfterGate, findPackageRoot, formatOutput, formatPhaseCompletionSummary, formatPipelineStatusHuman, formatPipelineSummary, formatTokenTelemetry, getSubstrateDefaultSettings, registerRunCommand, resolveBmadMethodSrcPath, resolveBmadMethodVersion, resolveMainRepoRoot, runAnalysisPhase, runMigrations, runPlanningPhase, runSolutioningPhase, validateStopAfterFromConflict } from "../run-D3ZscMlL.js";
+import { DatabaseWrapper, SUBSTRATE_OWNED_SETTINGS_KEYS, VALID_PHASES, buildPipelineStatusOutput, createContextCompiler, createDispatcher, createImplementationOrchestrator, createPackLoader, createPhaseOrchestrator, createStopAfterGate, findPackageRoot, formatOutput, formatPhaseCompletionSummary, formatPipelineStatusHuman, formatPipelineSummary, formatTokenTelemetry, getSubstrateDefaultSettings, parseDbTimestampAsUtc, registerRunCommand, resolveBmadMethodSrcPath, resolveBmadMethodVersion, resolveMainRepoRoot, runAnalysisPhase, runMigrations, runPlanningPhase, runSolutioningPhase, validateStopAfterFromConflict } from "../run-0IlA2ubQ.js";
 import { ConfigError, ConfigIncompatibleFormatError } from "../errors-BPqtzQ4U.js";
 import { addTokenUsage, createDecision, getDecisionsByPhaseForRun, getLatestRun, getPipelineRunById, getTokenUsageSummary, listRequirements, updatePipelineRun } from "../decisions-DNYByk0U.js";
-import { compareRunMetrics, getBaselineRunMetrics, getRunMetrics, getStoryMetricsForRun, incrementRunRestarts, listRunMetrics, tagRunAsBaseline } from "../metrics-BSg8VIHd.js";
+import { aggregateTokenUsageForRun, compareRunMetrics, getBaselineRunMetrics, getRunMetrics, getStoryMetricsForRun, incrementRunRestarts, listRunMetrics, tagRunAsBaseline } from "../metrics-BSg8VIHd.js";
 import { abortMerge, createWorktree, getConflictingFiles, getMergedFiles, getOrphanedWorktrees, performMerge, removeBranch, removeWorktree, simulateMerge, verifyGitVersion } from "../git-utils-BtI5eNoN.js";
 import { registerUpgradeCommand } from "../upgrade-rV26kdh3.js";
 import { createRequire } from "module";
@@ -2404,20 +2404,46 @@ function registerAmendCommand(program, _version = "0.0.0", projectRoot = process
 //#endregion
 //#region src/cli/commands/health.ts
 const logger$11 = createLogger("health-cmd");
-function inspectProcessTree() {
+/** 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`
+*/
+function isOrchestratorProcessLine(line) {
+	if (line.includes("grep")) return false;
+	if (line.includes("substrate run")) return true;
+	if (line.includes("substrate-ai run")) return true;
+	if (line.includes("index.js run")) return true;
+	if (line.includes("node") && /\srun(\s|$)/.test(line) && (line.includes("--events") || line.includes("--stories"))) return true;
+	return false;
+}
+function inspectProcessTree(execFileSyncOverride) {
 	const result = {
 		orchestrator_pid: null,
 		child_pids: [],
 		zombies: []
 	};
 	try {
-		const { execFileSync } = __require("node:child_process");
-		const psOutput = execFileSync("ps", ["-eo", "pid,ppid,stat,command"], {
+		let psOutput;
+		if (execFileSyncOverride !== void 0) psOutput = execFileSyncOverride("ps", ["-eo", "pid,ppid,stat,command"], {
 			encoding: "utf-8",
 			timeout: 5e3
 		});
+		else {
+			const { execFileSync } = __require("node:child_process");
+			psOutput = execFileSync("ps", ["-eo", "pid,ppid,stat,command"], {
+				encoding: "utf-8",
+				timeout: 5e3
+			});
+		}
 		const lines = psOutput.split("\n");
-		for (const line of lines) if (line.includes("substrate run") && !line.includes("grep")) {
+		for (const line of lines) if (isOrchestratorProcessLine(line)) {
 			const match = line.trim().match(/^(\d+)/);
 			if (match) {
 				result.orchestrator_pid = parseInt(match[1], 10);
@@ -2478,7 +2504,7 @@ async function getAutoHealthData(options) {
 		if (runId !== void 0) run = getPipelineRunById(db, runId);
 		else run = getLatestRun(db);
 		if (run === void 0) return NO_PIPELINE;
-		const updatedAt = new Date(run.updated_at);
+		const updatedAt = parseDbTimestampAsUtc(run.updated_at);
 		const stalenessSeconds = Math.round((Date.now() - updatedAt.getTime()) / 1e3);
 		let storyDetails = {};
 		let active = 0;
@@ -2500,8 +2526,9 @@ async function getAutoHealthData(options) {
 		} catch {}
 		const processInfo = inspectProcessTree();
 		let verdict = "NO_PIPELINE_RUNNING";
-		if (run.status === "running") if (processInfo.zombies.length > 0) verdict = "STALLED";
-		else if (stalenessSeconds > 600) verdict = "STALLED";
+		if (run.status === "running") if (processInfo.orchestrator_pid === null && active === 0 && completed > 0) verdict = "NO_PIPELINE_RUNNING";
+		else if (processInfo.zombies.length > 0) verdict = "STALLED";
+		else if (stalenessSeconds > DEFAULT_STALL_THRESHOLD_SECONDS) verdict = "STALLED";
 		else if (processInfo.orchestrator_pid !== null && processInfo.child_pids.length === 0 && active > 0) verdict = "STALLED";
 		else verdict = "HEALTHY";
 		else if (run.status === "completed" || run.status === "failed" || run.status === "stopped") verdict = "NO_PIPELINE_RUNNING";
@@ -2527,124 +2554,31 @@ async function getAutoHealthData(options) {
 	}
 }
 async function runHealthAction(options) {
-	const { outputFormat, runId, projectRoot } = options;
-	const dbRoot = await resolveMainRepoRoot(projectRoot);
-	const dbPath = join(dbRoot, ".substrate", "substrate.db");
-	if (!existsSync(dbPath)) {
-		const output = {
-			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: {}
-			}
-		};
-		if (outputFormat === "json") process.stdout.write(formatOutput(output, "json", true) + "\n");
-		else process.stdout.write("NO_PIPELINE_RUNNING — no substrate database found\n");
-		return 0;
-	}
-	const dbWrapper = new DatabaseWrapper(dbPath);
+	const { outputFormat } = options;
 	try {
-		dbWrapper.open();
-		const db = dbWrapper.db;
-		let run;
-		if (runId !== void 0) run = getPipelineRunById(db, runId);
-		else run = getLatestRun(db);
-		if (run === void 0) {
-			const output$1 = {
-				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: {}
-				}
-			};
-			if (outputFormat === "json") process.stdout.write(formatOutput(output$1, "json", true) + "\n");
-			else process.stdout.write("NO_PIPELINE_RUNNING — no pipeline runs found\n");
-			return 0;
-		}
-		const updatedAt = new Date(run.updated_at);
-		const stalenessSeconds = Math.round((Date.now() - updatedAt.getTime()) / 1e3);
-		let storyDetails = {};
-		let active = 0;
-		let completed = 0;
-		let escalated = 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") active++;
-				}
-			}
-		} catch {}
-		const processInfo = inspectProcessTree();
-		let verdict = "NO_PIPELINE_RUNNING";
-		if (run.status === "running") if (processInfo.zombies.length > 0) verdict = "STALLED";
-		else if (stalenessSeconds > 600) verdict = "STALLED";
-		else if (processInfo.orchestrator_pid !== null && processInfo.child_pids.length === 0 && active > 0) verdict = "STALLED";
-		else verdict = "HEALTHY";
-		else if (run.status === "completed" || run.status === "failed" || run.status === "stopped") verdict = "NO_PIPELINE_RUNNING";
-		const output = {
-			verdict,
-			run_id: run.id,
-			status: run.status,
-			current_phase: run.current_phase,
-			staleness_seconds: stalenessSeconds,
-			last_activity: run.updated_at,
-			process: processInfo,
-			stories: {
-				active,
-				completed,
-				escalated,
-				details: storyDetails
-			}
-		};
-		if (outputFormat === "json") process.stdout.write(formatOutput(output, "json", true) + "\n");
+		const health = await getAutoHealthData(options);
+		if (outputFormat === "json") process.stdout.write(formatOutput(health, "json", true) + "\n");
 		else {
-			const verdictLabel = verdict === "HEALTHY" ? "HEALTHY" : verdict === "STALLED" ? "STALLED" : "NO PIPELINE RUNNING";
+			const verdictLabel = health.verdict === "HEALTHY" ? "HEALTHY" : health.verdict === "STALLED" ? "STALLED" : "NO PIPELINE RUNNING";
 			process.stdout.write(`\nPipeline Health: ${verdictLabel}\n`);
-			process.stdout.write(`  Run:          ${run.id}\n`);
-			process.stdout.write(`  Status:       ${run.status}\n`);
-			process.stdout.write(`  Phase:        ${run.current_phase ?? "N/A"}\n`);
-			process.stdout.write(`  Last Active:  ${run.updated_at} (${stalenessSeconds}s ago)\n`);
-			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");
-			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: ${active} active, ${completed} completed, ${escalated} escalated\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`);
+				}
 			}
 		}
 		return 0;
@@ -2654,10 +2588,6 @@ async function runHealthAction(options) {
 		else process.stderr.write(`Error: ${msg}\n`);
 		logger$11.error({ err }, "health action failed");
 		return 1;
-	} finally {
-		try {
-			dbWrapper.close();
-		} catch {}
 	}
 }
 function registerHealthCommand(program, _version = "0.0.0", projectRoot = process.cwd()) {
@@ -2700,6 +2630,36 @@ function defaultSupervisorDeps() {
 				}
 			};
 		})(),
+		getTokenSnapshot: (runId, projectRoot) => {
+			try {
+				const dbPath = join(projectRoot, ".substrate", "substrate.db");
+				if (!existsSync(dbPath)) return {
+					input: 0,
+					output: 0,
+					cost_usd: 0
+				};
+				const dbWrapper = new DatabaseWrapper(dbPath);
+				try {
+					dbWrapper.open();
+					const agg = aggregateTokenUsageForRun(dbWrapper.db, runId);
+					return {
+						input: agg.input,
+						output: agg.output,
+						cost_usd: agg.cost
+					};
+				} finally {
+					try {
+						dbWrapper.close();
+					} catch {}
+				}
+			} catch {
+				return {
+					input: 0,
+					output: 0,
+					cost_usd: 0
+				};
+			}
+		},
 		runAnalysis: async (runId, projectRoot) => {
 			const dbPath = join(projectRoot, ".substrate", "substrate.db");
 			if (!existsSync(dbPath)) return;
@@ -2741,7 +2701,7 @@ function defaultSupervisorDeps() {
 */
 async function runSupervisorAction(options, deps = {}) {
 	const { pollInterval, stallThreshold, maxRestarts, outputFormat, projectRoot, runId, pack, experiment, maxExperiments } = options;
-	const { getHealth, killPid, resumePipeline, sleep, incrementRestarts, runAnalysis } = {
+	const { getHealth, killPid, resumePipeline, sleep, incrementRestarts, runAnalysis, getTokenSnapshot } = {
 		...defaultSupervisorDeps(),
 		...deps
 	};
@@ -2765,6 +2725,36 @@ async function runSupervisorAction(options, deps = {}) {
 			projectRoot
 		});
 		const ts = new Date().toISOString();
+		if (outputFormat === "json") {
+			const tokenSnapshot = health.run_id !== null ? getTokenSnapshot(health.run_id, projectRoot) : {
+				input: 0,
+				output: 0,
+				cost_usd: 0
+			};
+			const proc = health.process ?? {
+				orchestrator_pid: null,
+				child_pids: [],
+				zombies: []
+			};
+			emitEvent({
+				type: "supervisor:poll",
+				run_id: health.run_id,
+				verdict: health.verdict,
+				staleness_seconds: health.staleness_seconds,
+				stories: {
+					active: health.stories.active,
+					completed: health.stories.completed,
+					escalated: health.stories.escalated
+				},
+				story_details: health.stories.details,
+				tokens: tokenSnapshot,
+				process: {
+					orchestrator_pid: proc.orchestrator_pid,
+					child_count: proc.child_pids.length,
+					zombie_count: proc.zombies.length
+				}
+			});
+		}
 		log(`[${ts}] Health: ${health.verdict} | staleness=${health.staleness_seconds}s | stories: active=${health.stories.active} completed=${health.stories.completed} escalated=${health.stories.escalated}`);
 		if (health.verdict === "NO_PIPELINE_RUNNING") {
 			const elapsedSeconds = Math.round((Date.now() - startTime) / 1e3);
@@ -2843,7 +2833,7 @@ async function runSupervisorAction(options, deps = {}) {
 								const expDb = expDbWrapper.db;
 								const { runRunAction: runPipeline } = await import(
 									/* @vite-ignore */
-									"../run-Bwyy5-RY.js"
+									"../run-Chc5BzIz.js"
 );
 								const runStoryFn = async (opts) => {
 									const exitCode = await runPipeline({

package/dist/index.d.ts

@@ -231,6 +231,45 @@ interface StoryStallEvent {
   /** Milliseconds since the last progress event */
   elapsed_ms: number;
 }
+/**
+ * Emitted after each `getHealth()` call in the supervisor poll loop.
+ * Allows agents to observe health state, story progress, and token costs
+ * on every cycle without needing a separate health query.
+ */
+interface SupervisorPollEvent {
+  type: 'supervisor:poll';
+  /** ISO-8601 timestamp generated at emit time */
+  ts: string;
+  /** Current pipeline run ID, or null if no run is active */
+  run_id: string | null;
+  /** Health verdict from the most recent getHealth() call */
+  verdict: 'HEALTHY' | 'STALLED' | 'NO_PIPELINE_RUNNING';
+  /** Seconds since the last pipeline activity */
+  staleness_seconds: number;
+  /** Story counts from the health snapshot */
+  stories: {
+    active: number;
+    completed: number;
+    escalated: number;
+  };
+  /** Per-story phase and review cycle details */
+  story_details: Record<string, {
+    phase: string;
+    review_cycles: number;
+  }>;
+  /** Cumulative token/cost snapshot for the current run */
+  tokens: {
+    input: number;
+    output: number;
+    cost_usd: number;
+  };
+  /** Process health from the health snapshot */
+  process: {
+    orchestrator_pid: number | null;
+    child_count: number;
+    zombie_count: number;
+  };
+}
 /**
  * Emitted when the supervisor kills a stalled pipeline process tree.
  */
@@ -389,7 +428,7 @@ interface SupervisorExperimentErrorEvent {
  * }
  * ```
  */
-type PipelineEvent = PipelineStartEvent | PipelineCompleteEvent | StoryPhaseEvent | StoryDoneEvent | StoryEscalationEvent | StoryWarnEvent | StoryLogEvent | PipelineHeartbeatEvent | StoryStallEvent | SupervisorKillEvent | SupervisorRestartEvent | SupervisorAbortEvent | SupervisorSummaryEvent | SupervisorAnalysisCompleteEvent | SupervisorAnalysisErrorEvent | SupervisorExperimentStartEvent | SupervisorExperimentSkipEvent | SupervisorExperimentRecommendationsEvent | SupervisorExperimentCompleteEvent | SupervisorExperimentErrorEvent; //#endregion
+type PipelineEvent = PipelineStartEvent | PipelineCompleteEvent | StoryPhaseEvent | StoryDoneEvent | StoryEscalationEvent | StoryWarnEvent | StoryLogEvent | PipelineHeartbeatEvent | StoryStallEvent | SupervisorPollEvent | SupervisorKillEvent | SupervisorRestartEvent | SupervisorAbortEvent | SupervisorSummaryEvent | SupervisorAnalysisCompleteEvent | SupervisorAnalysisErrorEvent | SupervisorExperimentStartEvent | SupervisorExperimentSkipEvent | SupervisorExperimentRecommendationsEvent | SupervisorExperimentCompleteEvent | SupervisorExperimentErrorEvent; //#endregion
 //#region src/core/errors.d.ts
 
 /**