substrate-ai 0.1.19 → 0.1.21

package/dist/cli/index.js

@@ -3,6 +3,7 @@ import { AdapterRegistry, ConfigError, ConfigIncompatibleFormatError, DatabaseWr
 import { CURRENT_CONFIG_FORMAT_VERSION, CURRENT_TASK_GRAPH_VERSION, PartialSubstrateConfigSchema, SUPPORTED_CONFIG_FORMAT_VERSIONS, SubstrateConfigSchema } from "../config-schema-C9tTMcm1.js";
 import { defaultConfigMigrator } from "../version-manager-impl-O25ieEjS.js";
 import { registerUpgradeCommand } from "../upgrade-CHhsJc_q.js";
+import { createRequire } from "module";
 import { Command } from "commander";
 import { fileURLToPath } from "url";
 import { dirname, extname, isAbsolute, join, relative, resolve } from "path";
@@ -23,8 +24,12 @@ import * as readline$1 from "readline";
 import * as readline from "readline";
 import { createInterface as createInterface$1 } from "readline";
 import { randomUUID as randomUUID$1 } from "crypto";
-import { createRequire } from "node:module";
+import { createRequire as createRequire$1 } from "node:module";
 
+//#region rolldown:runtime
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+//#endregion
 //#region src/cli/utils/formatting.ts
 /**
 * Build adapter list rows from discovery results.
@@ -6492,6 +6497,70 @@ const PIPELINE_EVENT_METADATA = [
 				description: "Log message."
 			}
 		]
+	},
+	{
+		type: "pipeline:heartbeat",
+		description: "Periodic heartbeat emitted every 30s when no other progress events have fired.",
+		when: "Every 30 seconds during pipeline execution. Allows detection of stalled pipelines.",
+		fields: [
+			{
+				name: "ts",
+				type: "string",
+				description: "ISO-8601 timestamp generated at emit time."
+			},
+			{
+				name: "run_id",
+				type: "string",
+				description: "Pipeline run ID."
+			},
+			{
+				name: "active_dispatches",
+				type: "number",
+				description: "Number of sub-agents currently running."
+			},
+			{
+				name: "completed_dispatches",
+				type: "number",
+				description: "Number of dispatches completed."
+			},
+			{
+				name: "queued_dispatches",
+				type: "number",
+				description: "Number of dispatches waiting to start."
+			}
+		]
+	},
+	{
+		type: "story:stall",
+		description: "Emitted when the watchdog detects no progress for an extended period (default: 10 minutes).",
+		when: "When a story has shown no progress for longer than the watchdog timeout. Indicates likely stall.",
+		fields: [
+			{
+				name: "ts",
+				type: "string",
+				description: "ISO-8601 timestamp generated at emit time."
+			},
+			{
+				name: "run_id",
+				type: "string",
+				description: "Pipeline run ID."
+			},
+			{
+				name: "story_key",
+				type: "string",
+				description: "Story key that appears stalled."
+			},
+			{
+				name: "phase",
+				type: "string",
+				description: "Phase the story was in when stall was detected."
+			},
+			{
+				name: "elapsed_ms",
+				type: "number",
+				description: "Milliseconds since last progress event."
+			}
+		]
 	}
 ];
 /**
@@ -7214,6 +7283,13 @@ const DEFAULT_TIMEOUTS = {
 * Only defined for task types that benefit from explicit turn budgets.
 */
 const DEFAULT_MAX_TURNS = {
+	"analysis": 15,
+	"planning": 20,
+	"architecture": 25,
+	"story-generation": 30,
+	"readiness-check": 20,
+	"elicitation": 15,
+	"critique": 15,
 	"dev-story": 75,
 	"major-rework": 50,
 	"code-review": 25,
@@ -7900,6 +7976,23 @@ function createDecision(db, input) {
 	return row;
 }
 /**
+* Insert or update a decision record.
+* If a decision with the same pipeline_run_id, category, and key already exists,
+* update its value and rationale. Otherwise, insert a new record.
+*/
+function upsertDecision(db, input) {
+	const validated = CreateDecisionInputSchema.parse(input);
+	const existing = db.prepare("SELECT * FROM decisions WHERE pipeline_run_id = ? AND category = ? AND key = ? LIMIT 1").get(validated.pipeline_run_id ?? null, validated.category, validated.key);
+	if (existing) {
+		updateDecision(db, existing.id, {
+			value: validated.value,
+			rationale: validated.rationale ?? void 0
+		});
+		return db.prepare("SELECT * FROM decisions WHERE id = ?").get(existing.id);
+	}
+	return createDecision(db, input);
+}
+/**
 * Get all decisions for a given phase, ordered by created_at ascending.
 */
 function getDecisionsByPhase(db, phase) {
@@ -7915,6 +8008,26 @@ function getDecisionsByPhaseForRun(db, runId, phase) {
 	return stmt.all(runId, phase);
 }
 /**
+* Update a decision's value and/or rationale and set updated_at.
+*/
+function updateDecision(db, id, updates) {
+	const setClauses = [];
+	const values = [];
+	if (updates.value !== void 0) {
+		setClauses.push("value = ?");
+		values.push(updates.value);
+	}
+	if (updates.rationale !== void 0) {
+		setClauses.push("rationale = ?");
+		values.push(updates.rationale);
+	}
+	if (setClauses.length === 0) return;
+	setClauses.push("updated_at = datetime('now')");
+	values.push(id);
+	const stmt = db.prepare(`UPDATE decisions SET ${setClauses.join(", ")} WHERE id = ?`);
+	stmt.run(...values);
+}
+/**
 * Insert a new requirement with status = 'active'.
 */
 function createRequirement(db, input) {
@@ -10022,6 +10135,10 @@ function createImplementationOrchestrator(deps) {
 	const _stories = new Map();
 	let _paused = false;
 	let _pauseGate = null;
+	let _lastProgressTs = Date.now();
+	let _heartbeatTimer = null;
+	const HEARTBEAT_INTERVAL_MS = 3e4;
+	const WATCHDOG_TIMEOUT_MS = 6e5;
 	function getStatus() {
 		const stories = {};
 		for (const [key, s] of _stories) stories[key] = { ...s };
@@ -10043,6 +10160,7 @@ function createImplementationOrchestrator(deps) {
 	}
 	function persistState() {
 		if (config.pipelineRunId === void 0) return;
+		recordProgress();
 		try {
 			const serialized = JSON.stringify(getStatus());
 			updatePipelineRun(db, config.pipelineRunId, {
@@ -10053,6 +10171,50 @@ function createImplementationOrchestrator(deps) {
 			logger$31.warn("Failed to persist orchestrator state", { err });
 		}
 	}
+	function recordProgress() {
+		_lastProgressTs = Date.now();
+	}
+	function startHeartbeat() {
+		if (_heartbeatTimer !== null) return;
+		_heartbeatTimer = setInterval(() => {
+			if (_state !== "RUNNING") return;
+			let active = 0;
+			let completed = 0;
+			let queued = 0;
+			for (const s of _stories.values()) if (s.phase === "COMPLETE" || s.phase === "ESCALATED") completed++;
+			else if (s.phase === "PENDING") queued++;
+			else active++;
+			eventBus.emit("orchestrator:heartbeat", {
+				runId: config.pipelineRunId ?? "",
+				activeDispatches: active,
+				completedDispatches: completed,
+				queuedDispatches: queued
+			});
+			const elapsed = Date.now() - _lastProgressTs;
+			if (elapsed >= WATCHDOG_TIMEOUT_MS) {
+				for (const [key, s] of _stories) if (s.phase !== "PENDING" && s.phase !== "COMPLETE" && s.phase !== "ESCALATED") {
+					logger$31.warn({
+						storyKey: key,
+						phase: s.phase,
+						elapsedMs: elapsed
+					}, "Watchdog: possible stall detected");
+					eventBus.emit("orchestrator:stall", {
+						runId: config.pipelineRunId ?? "",
+						storyKey: key,
+						phase: s.phase,
+						elapsedMs: elapsed
+					});
+				}
+			}
+		}, HEARTBEAT_INTERVAL_MS);
+		if (_heartbeatTimer && typeof _heartbeatTimer === "object" && "unref" in _heartbeatTimer) _heartbeatTimer.unref();
+	}
+	function stopHeartbeat() {
+		if (_heartbeatTimer !== null) {
+			clearInterval(_heartbeatTimer);
+			_heartbeatTimer = null;
+		}
+	}
 	/**
 	* Wait until the orchestrator is un-paused (if currently paused).
 	*/
@@ -10770,6 +10932,8 @@ function createImplementationOrchestrator(deps) {
 			pipelineRunId: config.pipelineRunId
 		});
 		persistState();
+		recordProgress();
+		startHeartbeat();
 		if (projectRoot !== void 0) {
 			const seedResult = seedMethodologyContext(db, projectRoot);
 			if (seedResult.decisionsCreated > 0) logger$31.info({
@@ -10786,12 +10950,14 @@ function createImplementationOrchestrator(deps) {
 		try {
 			await runWithConcurrency(groups, config.maxConcurrency);
 		} catch (err) {
+			stopHeartbeat();
 			_state = "FAILED";
 			_completedAt = new Date().toISOString();
 			persistState();
 			logger$31.error("Orchestrator failed with unhandled error", { err });
 			return getStatus();
 		}
+		stopHeartbeat();
 		_state = "COMPLETE";
 		_completedAt = new Date().toISOString();
 		let completed = 0;
@@ -11835,12 +12001,14 @@ function createQualityGate(config) {
 
 //#endregion
 //#region src/modules/phase-orchestrator/phases/solutioning.ts
-/** Maximum total prompt token budget for architecture generation (3,000 tokens × 4 chars = 12,000 chars) */
-const MAX_ARCH_PROMPT_TOKENS = 3e3;
-const MAX_ARCH_PROMPT_CHARS = MAX_ARCH_PROMPT_TOKENS * 4;
-/** Maximum total prompt token budget for story generation (4,000 tokens × 4 chars = 16,000 chars) */
-const MAX_STORY_PROMPT_TOKENS = 4e3;
-const MAX_STORY_PROMPT_CHARS = MAX_STORY_PROMPT_TOKENS * 4;
+/** Base token budget for architecture generation (covers template + requirements) */
+const BASE_ARCH_PROMPT_TOKENS = 3e3;
+/** Base token budget for story generation (covers template + requirements + architecture) */
+const BASE_STORY_PROMPT_TOKENS = 4e3;
+/** Additional tokens per architecture decision injected into story generation prompt */
+const TOKENS_PER_DECISION = 100;
+/** Absolute maximum prompt tokens (model context safety margin) */
+const ABSOLUTE_MAX_PROMPT_TOKENS = 12e3;
 /** Placeholder in architecture prompt template */
 const REQUIREMENTS_PLACEHOLDER = "{{requirements}}";
 /** Amendment context framing block prefix */
@@ -11854,6 +12022,58 @@ const STORY_REQUIREMENTS_PLACEHOLDER = "{{requirements}}";
 const STORY_ARCHITECTURE_PLACEHOLDER = "{{architecture_decisions}}";
 /** Gap analysis placeholder used in retry prompt */
 const GAP_ANALYSIS_PLACEHOLDER = "{{gap_analysis}}";
+/** Priority order for decision categories when summarizing (higher priority kept first) */
+const DECISION_CATEGORY_PRIORITY = [
+	"data",
+	"auth",
+	"api",
+	"frontend",
+	"infra",
+	"observability",
+	"ci"
+];
+/**
+* Calculate the dynamic prompt token budget based on the number of decisions
+* that will be injected into the prompt.
+*
+* @param baseBudget - Base token budget for the phase
+* @param decisionCount - Number of decisions to inject
+* @returns Calculated token budget, capped at ABSOLUTE_MAX_PROMPT_TOKENS
+*/
+function calculateDynamicBudget(baseBudget, decisionCount) {
+	const budget = baseBudget + decisionCount * TOKENS_PER_DECISION;
+	return Math.min(budget, ABSOLUTE_MAX_PROMPT_TOKENS);
+}
+/**
+* Summarize architecture decisions into compact key:value one-liners,
+* dropping rationale and optionally dropping lower-priority categories
+* to fit within a character budget.
+*
+* @param decisions - Full architecture decisions from the decision store
+* @param maxChars - Maximum character budget for the summarized output
+* @returns Compact summary string
+*/
+function summarizeDecisions(decisions, maxChars) {
+	const sorted = [...decisions].sort((a, b) => {
+		const aCat = (a.category ?? "").toLowerCase();
+		const bCat = (b.category ?? "").toLowerCase();
+		const aIdx = DECISION_CATEGORY_PRIORITY.indexOf(aCat);
+		const bIdx = DECISION_CATEGORY_PRIORITY.indexOf(bCat);
+		const aPri = aIdx === -1 ? DECISION_CATEGORY_PRIORITY.length : aIdx;
+		const bPri = bIdx === -1 ? DECISION_CATEGORY_PRIORITY.length : bIdx;
+		return aPri - bPri;
+	});
+	const lines = ["## Architecture Decisions (Summarized)"];
+	let currentLength = lines[0].length;
+	for (const d of sorted) {
+		const truncatedValue = d.value.length > 120 ? d.value.slice(0, 117) + "..." : d.value;
+		const line = `- ${d.key}: ${truncatedValue}`;
+		if (currentLength + line.length + 1 > maxChars) break;
+		lines.push(line);
+		currentLength += line.length + 1;
+	}
+	return lines.join("\n");
+}
 /**
 * Format functional and non-functional requirements from the planning phase
 * into a compact text block suitable for prompt injection.
@@ -11932,17 +12152,19 @@ async function runArchitectureGeneration(deps, params) {
 	const template = await pack.getPrompt("architecture");
 	const formattedRequirements = formatRequirements(db, runId);
 	let prompt = template.replace(REQUIREMENTS_PLACEHOLDER, formattedRequirements);
+	const dynamicBudgetTokens = calculateDynamicBudget(BASE_ARCH_PROMPT_TOKENS, 0);
+	const dynamicBudgetChars = dynamicBudgetTokens * 4;
 	if (amendmentContext !== void 0 && amendmentContext !== "") {
 		const framingLen = AMENDMENT_CONTEXT_HEADER.length + AMENDMENT_CONTEXT_FOOTER.length;
-		const availableForContext = MAX_ARCH_PROMPT_CHARS - prompt.length - framingLen - TRUNCATED_MARKER.length;
+		const availableForContext = dynamicBudgetChars - prompt.length - framingLen - TRUNCATED_MARKER.length;
 		let contextToInject = amendmentContext;
 		if (availableForContext <= 0) contextToInject = "";
 		else if (amendmentContext.length > availableForContext) contextToInject = amendmentContext.slice(0, availableForContext) + TRUNCATED_MARKER;
 		if (contextToInject !== "") prompt += AMENDMENT_CONTEXT_HEADER + contextToInject + AMENDMENT_CONTEXT_FOOTER;
 	}
 	const estimatedTokens = Math.ceil(prompt.length / 4);
-	if (estimatedTokens > MAX_ARCH_PROMPT_TOKENS) return {
-		error: `Architecture prompt exceeds token budget: ${estimatedTokens} tokens (max ${MAX_ARCH_PROMPT_TOKENS})`,
+	if (estimatedTokens > dynamicBudgetTokens) return {
+		error: `Architecture prompt exceeds token budget: ${estimatedTokens} tokens (max ${dynamicBudgetTokens})`,
 		tokenUsage: zeroTokenUsage
 	};
 	const handle = dispatcher.dispatch({
@@ -11974,7 +12196,7 @@ async function runArchitectureGeneration(deps, params) {
 		tokenUsage
 	};
 	const decisions = parsed.architecture_decisions;
-	for (const decision of decisions) createDecision(db, {
+	for (const decision of decisions) upsertDecision(db, {
 		pipeline_run_id: runId,
 		phase: "solutioning",
 		category: "architecture",
@@ -12017,20 +12239,34 @@ async function runStoryGeneration(deps, params, gapAnalysis) {
 	};
 	const template = await pack.getPrompt("story-generation");
 	const formattedRequirements = formatRequirements(db, runId);
-	const formattedArchitecture = formatArchitectureDecisions(db, runId);
+	const archDecisions = getDecisionsByPhaseForRun(db, runId, "solutioning").filter((d) => d.category === "architecture");
+	const dynamicBudgetTokens = calculateDynamicBudget(BASE_STORY_PROMPT_TOKENS, archDecisions.length);
+	const dynamicBudgetChars = dynamicBudgetTokens * 4;
+	let formattedArchitecture = formatArchitectureDecisions(db, runId);
 	let prompt = template.replace(STORY_REQUIREMENTS_PLACEHOLDER, formattedRequirements).replace(STORY_ARCHITECTURE_PLACEHOLDER, formattedArchitecture);
 	if (gapAnalysis !== void 0) prompt = prompt.replace(GAP_ANALYSIS_PLACEHOLDER, gapAnalysis);
 	if (amendmentContext !== void 0 && amendmentContext !== "") {
 		const framingLen = AMENDMENT_CONTEXT_HEADER.length + AMENDMENT_CONTEXT_FOOTER.length;
-		const availableForContext = MAX_STORY_PROMPT_CHARS - prompt.length - framingLen - TRUNCATED_MARKER.length;
+		const availableForContext = dynamicBudgetChars - prompt.length - framingLen - TRUNCATED_MARKER.length;
 		let contextToInject = amendmentContext;
 		if (availableForContext <= 0) contextToInject = "";
 		else if (amendmentContext.length > availableForContext) contextToInject = amendmentContext.slice(0, availableForContext) + TRUNCATED_MARKER;
 		if (contextToInject !== "") prompt += AMENDMENT_CONTEXT_HEADER + contextToInject + AMENDMENT_CONTEXT_FOOTER;
 	}
-	const estimatedTokens = Math.ceil(prompt.length / 4);
-	if (estimatedTokens > MAX_STORY_PROMPT_TOKENS) return {
-		error: `Story generation prompt exceeds token budget: ${estimatedTokens} tokens (max ${MAX_STORY_PROMPT_TOKENS})`,
+	let estimatedTokens = Math.ceil(prompt.length / 4);
+	if (estimatedTokens > dynamicBudgetTokens) {
+		const availableForDecisions = dynamicBudgetChars - (prompt.length - formattedArchitecture.length);
+		formattedArchitecture = summarizeDecisions(archDecisions.map((d) => ({
+			key: d.key,
+			value: d.value,
+			category: d.category
+		})), Math.max(availableForDecisions, 200));
+		prompt = template.replace(STORY_REQUIREMENTS_PLACEHOLDER, formattedRequirements).replace(STORY_ARCHITECTURE_PLACEHOLDER, formattedArchitecture);
+		if (gapAnalysis !== void 0) prompt = prompt.replace(GAP_ANALYSIS_PLACEHOLDER, gapAnalysis);
+		estimatedTokens = Math.ceil(prompt.length / 4);
+	}
+	if (estimatedTokens > dynamicBudgetTokens) return {
+		error: `Story generation prompt exceeds token budget: ${estimatedTokens} tokens (max ${dynamicBudgetTokens})`,
 		tokenUsage: zeroTokenUsage
 	};
 	const handle = dispatcher.dispatch({
@@ -12063,7 +12299,7 @@ async function runStoryGeneration(deps, params, gapAnalysis) {
 	};
 	const epics = parsed.epics;
 	for (const [epicIndex, epic] of epics.entries()) {
-		createDecision(db, {
+		upsertDecision(db, {
 			pipeline_run_id: runId,
 			phase: "solutioning",
 			category: "epics",
@@ -12073,7 +12309,7 @@ async function runStoryGeneration(deps, params, gapAnalysis) {
 				description: epic.description
 			})
 		});
-		for (const story of epic.stories) createDecision(db, {
+		for (const story of epic.stories) upsertDecision(db, {
 			pipeline_run_id: runId,
 			phase: "solutioning",
 			category: "stories",
@@ -12200,7 +12436,23 @@ async function runSolutioningPhase(deps, params) {
 	let totalInput = 0;
 	let totalOutput = 0;
 	try {
-		const archResult = await runArchitectureGeneration(deps, params);
+		const existingArchArtifact = getArtifactByTypeForRun(deps.db, params.runId, "solutioning", "architecture");
+		let archResult;
+		if (existingArchArtifact) {
+			const existingDecisions = getDecisionsByPhaseForRun(deps.db, params.runId, "solutioning").filter((d) => d.category === "architecture");
+			archResult = {
+				decisions: existingDecisions.map((d) => ({
+					key: d.key,
+					value: d.value,
+					rationale: d.rationale ?? ""
+				})),
+				artifactId: existingArchArtifact.id,
+				tokenUsage: {
+					input: 0,
+					output: 0
+				}
+			};
+		} else archResult = await runArchitectureGeneration(deps, params);
 		totalInput += archResult.tokenUsage.input;
 		totalOutput += archResult.tokenUsage.output;
 		if ("error" in archResult) return {
@@ -12897,8 +13149,8 @@ const PACKAGE_ROOT = join(__dirname, "..", "..", "..");
 */
 function resolveBmadMethodSrcPath(fromDir = __dirname) {
 	try {
-		const require = createRequire(join(fromDir, "synthetic.js"));
-		const pkgJsonPath = require.resolve("bmad-method/package.json");
+		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;
@@ -12910,9 +13162,9 @@ function resolveBmadMethodSrcPath(fromDir = __dirname) {
 */
 function resolveBmadMethodVersion(fromDir = __dirname) {
 	try {
-		const require = createRequire(join(fromDir, "synthetic.js"));
-		const pkgJsonPath = require.resolve("bmad-method/package.json");
-		const pkg = require(pkgJsonPath);
+		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";
@@ -13033,7 +13285,9 @@ function buildPipelineStatusOutput(run, tokenSummary, decisionsCount, storiesCou
 			cost_usd: totalCost
 		},
 		decisions_count: decisionsCount,
-		stories_count: storiesCount
+		stories_count: storiesCount,
+		last_activity: run.updated_at,
+		staleness_seconds: Math.round((Date.now() - new Date(run.updated_at).getTime()) / 1e3)
 	};
 }
 /**
@@ -13669,6 +13923,26 @@ async function runAutoRun(options) {
 					msg: payload.msg
 				});
 			});
+			eventBus.on("orchestrator:heartbeat", (payload) => {
+				ndjsonEmitter.emit({
+					type: "pipeline:heartbeat",
+					ts: new Date().toISOString(),
+					run_id: payload.runId,
+					active_dispatches: payload.activeDispatches,
+					completed_dispatches: payload.completedDispatches,
+					queued_dispatches: payload.queuedDispatches
+				});
+			});
+			eventBus.on("orchestrator:stall", (payload) => {
+				ndjsonEmitter.emit({
+					type: "story:stall",
+					ts: new Date().toISOString(),
+					run_id: payload.runId,
+					story_key: payload.storyKey,
+					phase: payload.phase,
+					elapsed_ms: payload.elapsedMs
+				});
+			});
 		}
 		const orchestrator = createImplementationOrchestrator({
 			db,
@@ -13824,6 +14098,7 @@ async function runFullPipeline(options) {
 					});
 				}
 				if (result.result === "failed") {
+					updatePipelineRun(db, runId, { status: "failed" });
 					const errorMsg = `Analysis phase failed: ${result.error ?? "unknown error"}${result.details ? ` — ${result.details}` : ""}`;
 					if (outputFormat === "human") process.stderr.write(`Error: ${errorMsg}\n`);
 					else process.stdout.write(formatOutput(null, "json", false, errorMsg) + "\n");
@@ -13846,6 +14121,7 @@ async function runFullPipeline(options) {
 					});
 				}
 				if (result.result === "failed") {
+					updatePipelineRun(db, runId, { status: "failed" });
 					const errorMsg = `Planning phase failed: ${result.error ?? "unknown error"}${result.details ? ` — ${result.details}` : ""}`;
 					if (outputFormat === "human") process.stderr.write(`Error: ${errorMsg}\n`);
 					else process.stdout.write(formatOutput(null, "json", false, errorMsg) + "\n");
@@ -13868,6 +14144,7 @@ async function runFullPipeline(options) {
 					});
 				}
 				if (result.result === "failed") {
+					updatePipelineRun(db, runId, { status: "failed" });
 					const errorMsg = `Solutioning phase failed: ${result.error ?? "unknown error"}${result.details ? ` — ${result.details}` : ""}`;
 					if (outputFormat === "human") process.stderr.write(`Error: ${errorMsg}\n`);
 					else process.stdout.write(formatOutput(null, "json", false, errorMsg) + "\n");
@@ -14141,6 +14418,7 @@ async function runFullPipelineFromPhase(options) {
 					});
 				}
 				if (result.result === "failed") {
+					updatePipelineRun(db, runId, { status: "failed" });
 					const errorMsg = `Analysis phase failed: ${result.error ?? "unknown error"}`;
 					if (outputFormat === "human") process.stderr.write(`Error: ${errorMsg}\n`);
 					else process.stdout.write(formatOutput(null, "json", false, errorMsg) + "\n");
@@ -14160,6 +14438,7 @@ async function runFullPipelineFromPhase(options) {
 					});
 				}
 				if (result.result === "failed") {
+					updatePipelineRun(db, runId, { status: "failed" });
 					const errorMsg = `Planning phase failed: ${result.error ?? "unknown error"}`;
 					if (outputFormat === "human") process.stderr.write(`Error: ${errorMsg}\n`);
 					else process.stdout.write(formatOutput(null, "json", false, errorMsg) + "\n");
@@ -14179,6 +14458,7 @@ async function runFullPipelineFromPhase(options) {
 					});
 				}
 				if (result.result === "failed") {
+					updatePipelineRun(db, runId, { status: "failed" });
 					const errorMsg = `Solutioning phase failed: ${result.error ?? "unknown error"}`;
 					if (outputFormat === "human") process.stderr.write(`Error: ${errorMsg}\n`);
 					else process.stdout.write(formatOutput(null, "json", false, errorMsg) + "\n");
@@ -14365,6 +14645,175 @@ async function runAutoStatus(options) {
 		} catch {}
 	}
 }
+function inspectProcessTree() {
+	const result = {
+		orchestrator_pid: null,
+		child_pids: [],
+		zombies: []
+	};
+	try {
+		const { execFileSync } = __require("node:child_process");
+		const 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 auto run") && !line.includes("grep")) {
+			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$2 = parts[2];
+				if (ppid === result.orchestrator_pid && pid !== result.orchestrator_pid) {
+					result.child_pids.push(pid);
+					if (stat$2.includes("Z")) result.zombies.push(pid);
+				}
+			}
+		}
+	} catch {}
+	return result;
+}
+async function runAutoHealth(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);
+	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");
+		else {
+			const verdictLabel = verdict === "HEALTHY" ? "HEALTHY" : 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`);
+			}
+		}
+		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$3.error({ err }, "auto health failed");
+		return 1;
+	} finally {
+		try {
+			dbWrapper.close();
+		} catch {}
+	}
+}
 /**
 * Detect and apply supersessions after a phase completes in an amendment run.
 *
@@ -14552,6 +15001,7 @@ async function runAmendCommand(options) {
 					});
 				}
 				if (result.result === "failed") {
+					updatePipelineRun(db, amendmentRunId, { status: "failed" });
 					process.stderr.write(`Error: Analysis phase failed: ${result.error ?? "unknown error"}${result.details ? ` — ${result.details}` : ""}\n`);
 					return 1;
 				}
@@ -14573,6 +15023,7 @@ async function runAmendCommand(options) {
 					});
 				}
 				if (result.result === "failed") {
+					updatePipelineRun(db, amendmentRunId, { status: "failed" });
 					process.stderr.write(`Error: Planning phase failed: ${result.error ?? "unknown error"}${result.details ? ` — ${result.details}` : ""}\n`);
 					return 1;
 				}
@@ -14594,6 +15045,7 @@ async function runAmendCommand(options) {
 					});
 				}
 				if (result.result === "failed") {
+					updatePipelineRun(db, amendmentRunId, { status: "failed" });
 					process.stderr.write(`Error: Solutioning phase failed: ${result.error ?? "unknown error"}${result.details ? ` — ${result.details}` : ""}\n`);
 					return 1;
 				}
@@ -14730,6 +15182,15 @@ function registerAutoCommand(program, _version = "0.0.0", projectRoot = process.
 		});
 		process.exitCode = exitCode;
 	});
+	auto.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 exitCode = await runAutoHealth({
+			outputFormat,
+			runId: opts.runId,
+			projectRoot: opts.projectRoot
+		});
+		process.exitCode = exitCode;
+	});
 	auto.command("amend").description("Run an amendment pipeline against a completed run and an existing run").option("--concept <text>", "Amendment concept description (inline)").option("--concept-file <path>", "Path to concept file").option("--run-id <id>", "Parent run ID (defaults to latest completed run)").option("--stop-after <phase>", "Stop pipeline after this phase completes").option("--from <phase>", "Start pipeline from this phase").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) => {
 		const exitCode = await runAmendCommand({
 			concept: opts.concept,
@@ -15757,6 +16218,12 @@ function registerMonitorCommand(program, version = "0.0.0", projectRoot = proces
 //#endregion
 //#region src/cli/index.ts
 process.setMaxListeners(30);
+process.stdout.on("error", (err) => {
+	if (err.code === "EPIPE") process.exit(0);
+});
+process.stderr.on("error", (err) => {
+	if (err.code === "EPIPE") process.exit(0);
+});
 const logger = createLogger("cli");
 /** Resolve the package.json path relative to this file */
 async function getPackageVersion() {

package/dist/index.d.ts

@@ -197,6 +197,40 @@ interface StoryLogEvent {
   /** Log message */
   msg: string;
 }
+/**
+ * Emitted periodically (every 30s) when no other progress events have fired.
+ * Allows parent agents to distinguish "working silently" from "stuck".
+ */
+interface PipelineHeartbeatEvent {
+  type: 'pipeline:heartbeat';
+  /** ISO-8601 timestamp generated at emit time */
+  ts: string;
+  /** Unique identifier for the current pipeline run */
+  run_id: string;
+  /** Number of sub-agent dispatches currently running */
+  active_dispatches: number;
+  /** Number of dispatches that have completed */
+  completed_dispatches: number;
+  /** Number of dispatches waiting to start */
+  queued_dispatches: number;
+}
+/**
+ * Emitted when the watchdog timer detects no progress for an extended period.
+ * Indicates a likely stall that may require operator intervention.
+ */
+interface StoryStallEvent {
+  type: 'story:stall';
+  /** ISO-8601 timestamp generated at emit time */
+  ts: string;
+  /** Unique identifier for the current pipeline run */
+  run_id: string;
+  /** Story key that appears stalled */
+  story_key: string;
+  /** Phase the story was in when the stall was detected */
+  phase: string;
+  /** Milliseconds since the last progress event */
+  elapsed_ms: number;
+}
 /**
  * Discriminated union of all pipeline event types.
  *
@@ -209,7 +243,7 @@ interface StoryLogEvent {
  * }
  * ```
  */
-type PipelineEvent = PipelineStartEvent | PipelineCompleteEvent | StoryPhaseEvent | StoryDoneEvent | StoryEscalationEvent | StoryWarnEvent | StoryLogEvent; //#endregion
+type PipelineEvent = PipelineStartEvent | PipelineCompleteEvent | StoryPhaseEvent | StoryDoneEvent | StoryEscalationEvent | StoryWarnEvent | StoryLogEvent | PipelineHeartbeatEvent | StoryStallEvent; //#endregion
 //#region src/core/errors.d.ts
 
 /**
@@ -793,6 +827,20 @@ interface OrchestratorEvents {
   'orchestrator:paused': Record<string, never>;
   /** Implementation orchestrator has been resumed */
   'orchestrator:resumed': Record<string, never>;
+  /** Periodic heartbeat emitted every 30s during pipeline execution */
+  'orchestrator:heartbeat': {
+    runId: string;
+    activeDispatches: number;
+    completedDispatches: number;
+    queuedDispatches: number;
+  };
+  /** Watchdog detected no progress for an extended period */
+  'orchestrator:stall': {
+    runId: string;
+    storyKey: string;
+    phase: string;
+    elapsedMs: number;
+  };
 }
 
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "substrate-ai",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "Substrate — multi-agent orchestration daemon for AI coding agents",
   "type": "module",
   "license": "MIT",
@@ -64,6 +64,7 @@
     "js-yaml": "^4.1.1",
     "pino": "^9.6.0",
     "semver": "^7.6.3",
+    "substrate-ai": "^0.1.19",
     "zod": "^4.3.6"
   },
   "devDependencies": {