substrate-ai 0.2.10 → 0.2.13

package/dist/cli/index.js

@@ -2,7 +2,7 @@
 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, parseDbTimestampAsUtc, registerRunCommand, resolveBmadMethodSrcPath, resolveBmadMethodVersion, resolveMainRepoRoot, runAnalysisPhase, runMigrations, runPlanningPhase, runSolutioningPhase, validateStopAfterFromConflict } from "../run-XqzHIF6m.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-CoP8UQU3.js";
 import { ConfigError, ConfigIncompatibleFormatError } from "../errors-BPqtzQ4U.js";
 import { addTokenUsage, createDecision, getDecisionsByPhaseForRun, getLatestRun, getPipelineRunById, getTokenUsageSummary, listRequirements, updatePipelineRun } from "../decisions-DNYByk0U.js";
 import { aggregateTokenUsageForRun, compareRunMetrics, getBaselineRunMetrics, getRunMetrics, getStoryMetricsForRun, incrementRunRestarts, listRunMetrics, tagRunAsBaseline } from "../metrics-BSg8VIHd.js";
@@ -2414,16 +2414,24 @@ const DEFAULT_STALL_THRESHOLD_SECONDS = 600;
 *   - `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) {
+function isOrchestratorProcessLine(line, projectRoot) {
 	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) {
+	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("--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, execFileSync: execFileSyncOverride } = opts ?? {};
 	const result = {
 		orchestrator_pid: null,
 		child_pids: [],
@@ -2443,7 +2451,7 @@ function inspectProcessTree(execFileSyncOverride) {
 			});
 		}
 		const lines = psOutput.split("\n");
-		for (const line of lines) if (isOrchestratorProcessLine(line)) {
+		for (const line of lines) if (isOrchestratorProcessLine(line, projectRoot)) {
 			const match = line.trim().match(/^(\d+)/);
 			if (match) {
 				result.orchestrator_pid = parseInt(match[1], 10);
@@ -2466,6 +2474,58 @@ function inspectProcessTree(execFileSyncOverride) {
 	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 } = __require("node:child_process");
+			psOutput = execFileSync("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 [];
+	}
+}
+/**
 * Fetch pipeline health data as a structured object without any stdout side-effects.
 * Used by runSupervisorAction to poll health without formatting overhead.
 *
@@ -2524,10 +2584,11 @@ async function getAutoHealthData(options) {
 				}
 			}
 		} catch {}
-		const processInfo = inspectProcessTree();
+		const processInfo = inspectProcessTree({ projectRoot });
 		let verdict = "NO_PIPELINE_RUNNING";
 		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 (processInfo.orchestrator_pid !== null && processInfo.child_pids.length > 0 && stalenessSeconds > DEFAULT_STALL_THRESHOLD_SECONDS) verdict = "HEALTHY";
 		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";
@@ -2660,6 +2721,7 @@ function defaultSupervisorDeps() {
 				};
 			}
 		},
+		getAllDescendants: (rootPids) => getAllDescendantPids(rootPids),
 		runAnalysis: async (runId, projectRoot) => {
 			const dbPath = join(projectRoot, ".substrate", "substrate.db");
 			if (!existsSync(dbPath)) return;
@@ -2701,7 +2763,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, getTokenSnapshot } = {
+	const { getHealth, killPid, resumePipeline, sleep, incrementRestarts, runAnalysis, getTokenSnapshot, getAllDescendants } = {
 		...defaultSupervisorDeps(),
 		...deps
 	};
@@ -2833,7 +2895,7 @@ async function runSupervisorAction(options, deps = {}) {
 								const expDb = expDbWrapper.db;
 								const { runRunAction: runPipeline } = await import(
 									/* @vite-ignore */
-									"../run-CDdKFwfI.js"
+									"../run-B9IglY4m.js"
 );
 								const runStoryFn = async (opts) => {
 									const exitCode = await runPipeline({
@@ -2899,7 +2961,10 @@ async function runSupervisorAction(options, deps = {}) {
 			return failed.length > 0 || escalated.length > 0 ? 1 : 0;
 		}
 		if (health.staleness_seconds >= stallThreshold) {
-			const pids = [...health.process.orchestrator_pid !== null ? [health.process.orchestrator_pid] : [], ...health.process.child_pids];
+			const directPids = [...health.process.orchestrator_pid !== null ? [health.process.orchestrator_pid] : [], ...health.process.child_pids];
+			const descendantPids = getAllDescendants(directPids);
+			const directPidSet = new Set(directPids);
+			const pids = [...directPids, ...descendantPids.filter((p) => !directPidSet.has(p))];
 			emitEvent({
 				type: "supervisor:kill",
 				run_id: health.run_id,
@@ -2973,6 +3038,7 @@ async function runSupervisorAction(options, deps = {}) {
 function registerSupervisorCommand(program, _version = "0.0.0", projectRoot = process.cwd()) {
 	program.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).option("--max-experiments <n>", "Maximum number of experiments to run per analysis cycle (default: 2, Story 17-4 AC6)", (v) => parseInt(v, 10), 2).action(async (opts) => {
 		const outputFormat = opts.outputFormat === "json" ? "json" : "human";
+		if (opts.stallThreshold < 120) console.warn(`Warning: --stall-threshold ${opts.stallThreshold}s is below 120s. Agent steps typically take 45-90s. This may cause false stall detections and wasted restarts.`);
 		const exitCode = await runSupervisorAction({
 			pollInterval: opts.pollInterval,
 			stallThreshold: opts.stallThreshold,

package/dist/index.d.ts

@@ -1025,6 +1025,8 @@ interface OrchestratorEvents {
     storyKey: string;
     phase: string;
     elapsedMs: number;
+    /** PID of the stalled child process, or null if not tracked */
+    childPid: number | null;
   };
   /** Readiness check has completed — emitted for all verdicts (READY, NEEDS_WORK, NOT_READY) */
   'solutioning:readiness-check': {

package/dist/{run-CDdKFwfI.js → run-B9IglY4m.js}

@@ -1,6 +1,6 @@
 import "./logger-C6n1g8uP.js";
 import "./event-bus-J-bw-pkp.js";
-import { registerRunCommand, runRunAction } from "./run-XqzHIF6m.js";
+import { registerRunCommand, runRunAction } from "./run-CoP8UQU3.js";
 import "./decisions-DNYByk0U.js";
 import "./metrics-BSg8VIHd.js";
 

package/dist/{run-XqzHIF6m.js → run-CoP8UQU3.js}

@@ -1202,6 +1202,15 @@ function buildPipelineStatusOutput(run, tokenSummary, decisionsCount, storiesCou
 		totalOutput += row.total_output_tokens;
 		totalCost += row.total_cost_usd;
 	}
+	let activeDispatches = 0;
+	try {
+		if (run.token_usage_json) {
+			const state = JSON.parse(run.token_usage_json);
+			if (state.stories) {
+				for (const s of Object.values(state.stories)) if (s.phase !== "PENDING" && s.phase !== "COMPLETE" && s.phase !== "ESCALATED") activeDispatches++;
+			}
+		}
+	} catch {}
 	return {
 		run_id: run.id,
 		current_phase: currentPhase,
@@ -1214,7 +1223,9 @@ function buildPipelineStatusOutput(run, tokenSummary, decisionsCount, storiesCou
 		decisions_count: decisionsCount,
 		stories_count: storiesCount,
 		last_activity: run.updated_at,
-		staleness_seconds: Math.round((Date.now() - parseDbTimestampAsUtc(run.updated_at).getTime()) / 1e3)
+		staleness_seconds: Math.round((Date.now() - parseDbTimestampAsUtc(run.updated_at).getTime()) / 1e3),
+		last_event_ts: run.updated_at,
+		active_dispatches: activeDispatches
 	};
 }
 /**
@@ -2215,10 +2226,14 @@ Options:
 - \`--stories <keys>\` — Comma-separated story keys to process (e.g., \`7-1,7-2\`)
 - \`--verbose\` — Enable verbose logging output
 - \`--pack <name>\` — Methodology pack name (default: bmad)
-- \`--from <phase>\` — Start from this phase: analysis, planning, solutioning, implementation
+- \`--from <phase>\` — Start from this phase: research, analysis, planning, solutioning, implementation
 - \`--stop-after <phase>\` — Stop pipeline after this phase completes
 - \`--concurrency <n>\` — Maximum parallel conflict groups (default: 3)
 - \`--output-format <format>\` — Output format: human (default) or json
+- \`--concept <text>\` — Inline concept text (required when --from analysis)
+- \`--research\` — Enable the research phase even if not set in the pack config
+- \`--skip-research\` — Skip the research phase even if enabled in the pack config
+- \`--skip-ux\` — Skip the UX design phase even if enabled in the pack config
 - \`--help-agent\` — Print this agent instruction fragment and exit
 
 Examples:
@@ -2285,12 +2300,51 @@ Options:
 - \`--analysis <run-id>\` — Read and output the analysis report with optimization recommendations for a specific run
 - \`--output-format <format>\` — Output format: human (default) or json
 
+### substrate export
+Export decision store contents as human-readable markdown files.
+
+\`\`\`
+substrate export [options]
+\`\`\`
+
+Options:
+- \`--run-id <id>\` — Pipeline run ID to export (defaults to latest run)
+- \`--output-dir <path>\` — Directory to write exported files to (default: _bmad-output/planning-artifacts/)
+- \`--output-format <format>\` — Output format: human (default) or json
+
 ### substrate health
 Check pipeline health, stall detection, and process status.
 
 \`\`\`
 substrate health [--output-format json]
 \`\`\`
+
+### substrate cost
+Show cost breakdown for the current session.
+
+\`\`\`
+substrate cost [--output-format json]
+\`\`\`
+
+### substrate amend
+Run an amendment pipeline against a completed run.
+
+\`\`\`
+substrate amend [options]
+\`\`\`
+
+### substrate brainstorm
+Interactive multi-persona brainstorm session with Pragmatic Engineer, Product Thinker, and Devil's Advocate.
+
+\`\`\`
+substrate brainstorm [options]
+\`\`\`
+
+Session commands: \`!wrap\` (save & exit), \`!quit\` (exit without saving), \`!help\`
+
+## Environment Variables
+
+- \`SUBSTRATE_MEMORY_THRESHOLD_MB\` — Override the free-memory threshold (in MB) for agent dispatch. Default: 512. On macOS, the conservative memory detection may report low availability even when ample RAM exists. Lower this (e.g., 256) if pipelines stall due to memory pressure false positives.
 `;
 }
 /**
@@ -2842,7 +2896,14 @@ const logger$12 = createLogger("agent-dispatch");
 const SHUTDOWN_GRACE_MS = 1e4;
 const SHUTDOWN_MAX_WAIT_MS = 3e4;
 const CHARS_PER_TOKEN = 4;
-const MIN_FREE_MEMORY_BYTES = 512 * 1024 * 1024;
+const MIN_FREE_MEMORY_BYTES = (() => {
+	const envMB = process.env.SUBSTRATE_MEMORY_THRESHOLD_MB;
+	if (envMB) {
+		const parsed = parseInt(envMB, 10);
+		if (!isNaN(parsed) && parsed >= 0) return parsed * 1024 * 1024;
+	}
+	return 512 * 1024 * 1024;
+})();
 const MEMORY_PRESSURE_POLL_MS = 1e4;
 /**
 * Get available system memory in bytes, accounting for platform differences.
@@ -5309,6 +5370,7 @@ function createImplementationOrchestrator(deps) {
 	let _heartbeatTimer = null;
 	const HEARTBEAT_INTERVAL_MS = 3e4;
 	const WATCHDOG_TIMEOUT_MS = 6e5;
+	const _stalledStories = new Set();
 	const _phaseStartMs = new Map();
 	const _phaseEndMs = new Map();
 	const _storyDispatches = new Map();
@@ -5404,6 +5466,7 @@ function createImplementationOrchestrator(deps) {
 	}
 	function recordProgress() {
 		_lastProgressTs = Date.now();
+		_stalledStories.clear();
 	}
 	function startHeartbeat() {
 		if (_heartbeatTimer !== null) return;
@@ -5415,7 +5478,8 @@ function createImplementationOrchestrator(deps) {
 			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", {
+			const timeSinceProgress = Date.now() - _lastProgressTs;
+			if (timeSinceProgress >= HEARTBEAT_INTERVAL_MS) eventBus.emit("orchestrator:heartbeat", {
 				runId: config.pipelineRunId ?? "",
 				activeDispatches: active,
 				completedDispatches: completed,
@@ -5424,6 +5488,8 @@ function createImplementationOrchestrator(deps) {
 			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") {
+					if (_stalledStories.has(key)) continue;
+					_stalledStories.add(key);
 					logger$16.warn({
 						storyKey: key,
 						phase: s.phase,
@@ -5433,7 +5499,8 @@ function createImplementationOrchestrator(deps) {
 						runId: config.pipelineRunId ?? "",
 						storyKey: key,
 						phase: s.phase,
-						elapsedMs: elapsed
+						elapsedMs: elapsed,
+						childPid: null
 					});
 				}
 			}
@@ -6194,7 +6261,7 @@ function createImplementationOrchestrator(deps) {
 		});
 		persistState();
 		recordProgress();
-		startHeartbeat();
+		if (config.enableHeartbeat) startHeartbeat();
 		if (projectRoot !== void 0) {
 			const seedResult = seedMethodologyContext(db, projectRoot);
 			if (seedResult.decisionsCreated > 0) logger$16.info({
@@ -10647,7 +10714,8 @@ async function runRunAction(options) {
 					run_id: payload.runId,
 					story_key: payload.storyKey,
 					phase: payload.phase,
-					elapsed_ms: payload.elapsedMs
+					elapsed_ms: payload.elapsedMs,
+					child_pid: payload.childPid
 				});
 			});
 		}
@@ -10660,7 +10728,8 @@ async function runRunAction(options) {
 			config: {
 				maxConcurrency: concurrency,
 				maxReviewCycles: 2,
-				pipelineRunId: pipelineRun.id
+				pipelineRunId: pipelineRun.id,
+				enableHeartbeat: eventsFlag === true
 			},
 			projectRoot
 		});
@@ -11103,4 +11172,4 @@ function registerRunCommand(program, _version = "0.0.0", projectRoot = process.c
 
 //#endregion
 export { 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, runRunAction, runSolutioningPhase, validateStopAfterFromConflict };
-//# sourceMappingURL=run-XqzHIF6m.js.map
+//# sourceMappingURL=run-CoP8UQU3.js.map

package/package.json

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