substrate-ai 0.15.0 → 0.16.0

package/dist/cli/index.js

@@ -4,7 +4,7 @@ import { createLogger } from "../logger-KeHncl-f.js";
 import { createEventBus } from "../helpers-CElYrONe.js";
 import { AdapterRegistry, BudgetConfigSchema, CURRENT_CONFIG_FORMAT_VERSION, CURRENT_TASK_GRAPH_VERSION, ConfigError, CostTrackerConfigSchema, DEFAULT_CONFIG, DoltClient, DoltNotInstalled, EXPERIMENT_RESULT, GlobalSettingsSchema, IngestionServer, MonitorDatabaseImpl, OPERATIONAL_FINDING, PartialGlobalSettingsSchema, PartialProviderConfigSchema, ProvidersSchema, RoutingRecommender, STORY_METRICS, TelemetryConfigSchema, addTokenUsage, aggregateTokenUsageForRun, checkDoltInstalled, compareRunMetrics, createAmendmentRun, createConfigSystem, createDecision, createDoltClient, createPipelineRun, getActiveDecisions, getAllCostEntriesFiltered, getBaselineRunMetrics, getDecisionsByCategory, getDecisionsByPhaseForRun, getLatestCompletedRun, getLatestRun, getPipelineRunById, getPlanningCostTotal, getRetryableEscalations, getRunMetrics, getSessionCostSummary, getSessionCostSummaryFiltered, getStoryMetricsForRun, getTokenUsageSummary, incrementRunRestarts, initSchema, initializeDolt, listRequirements, listRunMetrics, loadParentRunDecisions, supersedeDecision, tagRunAsBaseline, updatePipelineRun } from "../dist-CLvAwmT7.js";
 import "../adapter-registry-DXLMTmfD.js";
-import { AdapterTelemetryPersistence, AppError, DoltRepoMapMetaRepository, DoltSymbolRepository, ERR_REPO_MAP_STORAGE_WRITE, GitClient, GrammarLoader, RepoMapInjector, RepoMapModule, RepoMapQueryEngine, RepoMapStorage, SymbolParser, createContextCompiler, createDispatcher, createEventEmitter, createImplementationOrchestrator, createPackLoader, createPhaseOrchestrator, createStopAfterGate, createTelemetryAdvisor, formatPhaseCompletionSummary, getFactoryRunSummaries, getScenarioResultsForRun, listGraphRuns, registerFactoryCommand, registerRunCommand, registerScenariosCommand, resolveStoryKeys, runAnalysisPhase, runPlanningPhase, runSolutioningPhase, validateStopAfterFromConflict } from "../run-bhGoAbu9.js";
+import { AdapterTelemetryPersistence, AppError, DoltRepoMapMetaRepository, DoltSymbolRepository, ERR_REPO_MAP_STORAGE_WRITE, GitClient, GrammarLoader, RepoMapInjector, RepoMapModule, RepoMapQueryEngine, RepoMapStorage, SymbolParser, createContextCompiler, createDispatcher, createEventEmitter, createImplementationOrchestrator, createPackLoader, createPhaseOrchestrator, createStopAfterGate, createTelemetryAdvisor, formatPhaseCompletionSummary, getFactoryRunSummaries, getScenarioResultsForRun, getTwinRunsForRun, listGraphRuns, registerFactoryCommand, registerRunCommand, registerScenariosCommand, resolveStoryKeys, runAnalysisPhase, runPlanningPhase, runSolutioningPhase, validateStopAfterFromConflict } from "../run-z84Uu_U2.js";
 import "../errors-D1LU8CZ9.js";
 import "../routing-CcBOCuC9.js";
 import "../decisions-C0pz9Clx.js";
@@ -4359,7 +4359,7 @@ async function runSupervisorAction(options, deps = {}) {
 								await initSchema(expAdapter);
 								const { runRunAction: runPipeline } = await import(
 									/* @vite-ignore */
-									"../run-BQmRdbhV.js"
+									"../run-Q2TZstl9.js"
 );
 								const runStoryFn = async (opts) => {
 									const exitCode = await runPipeline({
@@ -4998,6 +4998,19 @@ async function runMetricsAction(options) {
 					const execAt = String(r.executed_at).slice(0, 19);
 					process.stdout.write(`  ${String(r.iteration).padStart(3)} ${scoreStr.padStart(7)} ${passesStr.padStart(7)} ${passedTotal.padStart(13)} ${execAt.padEnd(20)}\n`);
 				}
+				try {
+					const twinRuns = await getTwinRunsForRun(adapter, resolvedRunId);
+					if (twinRuns.length > 0) {
+						process.stdout.write("\nTwins:\n");
+						for (const twin of twinRuns) {
+							const ports = twin.ports.map((p) => `${p.host}:${p.container}`).join(", ");
+							const stoppedAt = twin.stopped_at ?? "still running";
+							process.stdout.write(`  ${twin.twin_name} [${twin.status}] ports: ${ports || "none"} started: ${twin.started_at} stopped: ${stoppedAt} health failures: ${twin.health_failure_count}\n`);
+						}
+					}
+				} catch (err) {
+					logger$10.debug({ err }, "getTwinRunsForRun failed — twin_runs table may not exist yet");
+				}
 			}
 			return 0;
 		}

package/dist/{run-BQmRdbhV.js → run-Q2TZstl9.js}

@@ -2,7 +2,7 @@ import "./health-DswaC1q5.js";
 import "./logger-KeHncl-f.js";
 import "./helpers-CElYrONe.js";
 import "./dist-CLvAwmT7.js";
-import { normalizeGraphSummaryToStatus, registerRunCommand, runRunAction } from "./run-bhGoAbu9.js";
+import { normalizeGraphSummaryToStatus, registerRunCommand, runRunAction } from "./run-z84Uu_U2.js";
 import "./routing-CcBOCuC9.js";
 import "./decisions-C0pz9Clx.js";
 

package/dist/{run-bhGoAbu9.js → run-z84Uu_U2.js}

@@ -7,12 +7,13 @@ import { access, readFile, readdir, stat } from "fs/promises";
 import { EventEmitter } from "node:events";
 import yaml from "js-yaml";
 import * as actualFS from "node:fs";
-import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { execFile, execSync, spawn } from "node:child_process";
-import path, { dirname as dirname$1, extname as extname$1, join as join$1, posix, win32 } from "node:path";
+import path, { dirname as dirname$1, extname as extname$1, join as join$1, posix, resolve as resolve$1, win32 } from "node:path";
+import { tmpdir } from "node:os";
 import { createHash, randomUUID } from "node:crypto";
 import { z } from "zod";
-import { lstat, mkdir as mkdir$1, readFile as readFile$1, readdir as readdir$1, readlink, realpath, stat as stat$1, writeFile as writeFile$1 } from "node:fs/promises";
+import { access as access$1, lstat, mkdir as mkdir$1, readFile as readFile$1, readdir as readdir$1, readlink, realpath, stat as stat$1, unlink, writeFile as writeFile$1 } from "node:fs/promises";
 import { existsSync as existsSync$1, lstatSync, mkdirSync as mkdirSync$1, readFileSync as readFileSync$1, readdir as readdir$2, readdirSync as readdirSync$1, readlinkSync, realpathSync, unlinkSync, writeFileSync as writeFileSync$1 } from "fs";
 import { fileURLToPath } from "node:url";
 import { createHash as createHash$1 } from "crypto";
@@ -23174,6 +23175,7 @@ function createGraphExecutor() {
 			firstResumedFidelity = "";
 			const startedAt = Date.now();
 			let outcome = await dispatchWithRetry(nodeToDispatch, context, graph, config, nodeRetries);
+			if (Date.now() - startedAt < 50) await new Promise((r) => setTimeout(r, 50));
 			if (outcome.status === "PARTIAL_SUCCESS" && !nodeToDispatch.allowPartial) outcome = {
 				...outcome,
 				status: "FAIL",
@@ -27315,7 +27317,7 @@ var Pattern = class Pattern {
 	#isUNC;
 	#isAbsolute;
 	#followGlobstar = true;
-	constructor(patternList, globList, index, platform) {
+	constructor(patternList, globList, index, platform$1) {
 		if (!isPatternList(patternList)) throw new TypeError("empty pattern list");
 		if (!isGlobList(globList)) throw new TypeError("empty glob list");
 		if (globList.length !== patternList.length) throw new TypeError("mismatched pattern list and glob list lengths");
@@ -27324,7 +27326,7 @@ var Pattern = class Pattern {
 		this.#patternList = patternList;
 		this.#globList = globList;
 		this.#index = index;
-		this.#platform = platform;
+		this.#platform = platform$1;
 		if (this.#index === 0) {
 			if (this.isUNC()) {
 				const [p0, p1, p2, p3, ...prest] = this.#patternList;
@@ -27471,12 +27473,12 @@ var Ignore = class {
 	absoluteChildren;
 	platform;
 	mmopts;
-	constructor(ignored, { nobrace, nocase, noext, noglobstar, platform = defaultPlatform$1 }) {
+	constructor(ignored, { nobrace, nocase, noext, noglobstar, platform: platform$1 = defaultPlatform$1 }) {
 		this.relative = [];
 		this.absolute = [];
 		this.relativeChildren = [];
 		this.absoluteChildren = [];
-		this.platform = platform;
+		this.platform = platform$1;
 		this.mmopts = {
 			dot: true,
 			nobrace,
@@ -27484,7 +27486,7 @@ var Ignore = class {
 			noext,
 			noglobstar,
 			optimizationLevel: 2,
-			platform,
+			platform: platform$1,
 			nocomment: true,
 			nonegate: true
 		};
@@ -28375,14 +28377,24 @@ function getExecutionCommand(filePath) {
 }
 /**
 * Run a single scenario file and return its result.
+*
+* @param entry       - Scenario entry with name and path.
+* @param projectRoot - Working directory for scenario execution.
+* @param env         - Optional extra environment variables to inject into the subprocess.
+*                      When provided, merged on top of `process.env`.
 */
-function runScenario(entry, projectRoot) {
+function runScenario(entry, projectRoot, env) {
 	return new Promise((resolve$2) => {
 		const startTime = Date.now();
 		const command = getExecutionCommand(entry.path);
+		const spawnEnv = env != null ? {
+			...process.env,
+			...env
+		} : void 0;
 		const child = spawn$1(command, [], {
 			cwd: projectRoot,
-			shell: true
+			shell: true,
+			env: spawnEnv
 		});
 		let stdoutBuf = "";
 		let stderrBuf = "";
@@ -28426,25 +28438,93 @@ function runScenario(entry, projectRoot) {
 	});
 }
 /**
+* Build a ScenarioRunResult where every scenario is marked as failed due to
+* a twin startup error. No scripts were executed.
+*/
+function buildStartupFailureResult(scenarioEntries, err) {
+	const scenarios = scenarioEntries.map((entry) => ({
+		name: entry.name,
+		status: "fail",
+		exitCode: -1,
+		stdout: "",
+		stderr: err.message,
+		durationMs: 0
+	}));
+	return {
+		scenarios,
+		summary: {
+			total: scenarios.length,
+			passed: 0,
+			failed: scenarios.length
+		},
+		durationMs: 0
+	};
+}
+/**
 * Create a ScenarioRunner that executes all scenarios in a manifest.
 *
-* @param _options - Optional configuration (currently reserved for future use).
+* @param options - Optional configuration including twin coordinator and timeout.
 */
-function createScenarioRunner(_options) {
+function createScenarioRunner(options) {
 	return { async run(manifest, projectRoot) {
 		const startTime = Date.now();
-		const scenarios = await Promise.all(manifest.scenarios.map((entry) => runScenario(entry, projectRoot)));
-		const passed = scenarios.filter((s$1) => s$1.status === "pass").length;
-		const failed = scenarios.filter((s$1) => s$1.status === "fail").length;
-		return {
-			scenarios,
-			summary: {
-				total: scenarios.length,
-				passed,
-				failed
-			},
-			durationMs: Date.now() - startTime
-		};
+		const { twinCoordinator } = options ?? {};
+		const requiresTwins = (manifest.twins?.length ?? 0) > 0 && twinCoordinator != null;
+		if (!requiresTwins) {
+			if (options?.twinHealthMonitor) {
+				const healthStatus = options.twinHealthMonitor.getStatus();
+				const unhealthyNames = Object.entries(healthStatus).filter(([, s$1]) => s$1 === "unhealthy").map(([name]) => name);
+				if (unhealthyNames.length > 0) {
+					const msg = unhealthyNames.map((n$1) => `Twin '${n$1}' is unhealthy`).join("; ");
+					return buildStartupFailureResult(manifest.scenarios, new Error(msg));
+				}
+			}
+			const scenarios = await Promise.all(manifest.scenarios.map((entry) => runScenario(entry, projectRoot)));
+			const passed = scenarios.filter((s$1) => s$1.status === "pass").length;
+			const failed = scenarios.filter((s$1) => s$1.status === "fail").length;
+			return {
+				scenarios,
+				summary: {
+					total: scenarios.length,
+					passed,
+					failed
+				},
+				durationMs: Date.now() - startTime
+			};
+		}
+		let twinEnv;
+		try {
+			twinEnv = await twinCoordinator.startTwins(manifest.twins);
+		} catch (err) {
+			return buildStartupFailureResult(manifest.scenarios, err);
+		}
+		if (options?.twinHealthMonitor) {
+			const healthStatus = options.twinHealthMonitor.getStatus();
+			const unhealthyNames = Object.entries(healthStatus).filter(([, s$1]) => s$1 === "unhealthy").map(([name]) => name);
+			if (unhealthyNames.length > 0) {
+				const msg = unhealthyNames.map((n$1) => `Twin '${n$1}' is unhealthy`).join("; ");
+				try {
+					await twinCoordinator.stopTwins();
+				} catch {}
+				return buildStartupFailureResult(manifest.scenarios, new Error(msg));
+			}
+		}
+		try {
+			const scenarios = await Promise.all(manifest.scenarios.map((entry) => runScenario(entry, projectRoot, twinEnv)));
+			const passed = scenarios.filter((s$1) => s$1.status === "pass").length;
+			const failed = scenarios.filter((s$1) => s$1.status === "fail").length;
+			return {
+				scenarios,
+				summary: {
+					total: scenarios.length,
+					passed,
+					failed
+				},
+				durationMs: Date.now() - startTime
+			};
+		} finally {
+			await twinCoordinator.stopTwins();
+		}
 	} };
 }
 
@@ -28487,6 +28567,455 @@ function registerScenariosCommand(program) {
 	});
 }
 
+//#endregion
+//#region packages/factory/dist/twins/schema.js
+/**
+* Validates and transforms a "host:container" port string into a PortMapping object.
+*/
+const portMappingStringSchema = z.string().regex(/^\d+:\d+$/, "Port mapping must be in \"host:container\" format (e.g., \"5432:5432\")").transform((val) => {
+	const parts = val.split(":");
+	const host = Number(parts[0]);
+	const container = Number(parts[1]);
+	return {
+		host,
+		container
+	};
+});
+/**
+* Validates a healthcheck configuration object.
+*/
+const twinHealthcheckSchema = z.object({
+	url: z.string().url("Healthcheck URL must be a valid URL"),
+	interval_ms: z.number().int().positive().default(500),
+	timeout_ms: z.number().int().positive().default(1e4)
+});
+/**
+* Validates a full twin definition. Unknown fields are rejected via `.strict()`.
+*/
+const twinDefinitionSchema = z.object({
+	name: z.string().min(1, "Twin name must not be empty"),
+	image: z.string().min(1, "Twin image must not be empty"),
+	ports: z.array(portMappingStringSchema).default([]),
+	environment: z.record(z.string(), z.string()).default({}),
+	healthcheck: twinHealthcheckSchema.optional()
+}).strict();
+const TwinDefinitionSchema = twinDefinitionSchema;
+
+//#endregion
+//#region packages/factory/dist/twins/types.js
+/**
+* Twin Registry — Type definitions for TwinDefinition and related interfaces.
+*
+* Story 47-1.
+*/
+/**
+* Thrown when a single twin definition file fails validation or parsing.
+*/
+var TwinDefinitionError = class extends Error {
+	sourceFile;
+	constructor(message, sourceFile) {
+		super(message);
+		this.sourceFile = sourceFile;
+		this.name = "TwinDefinitionError";
+	}
+};
+/**
+* Thrown when a registry-level constraint is violated (e.g., duplicate twin names).
+*/
+var TwinRegistryError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "TwinRegistryError";
+	}
+};
+
+//#endregion
+//#region packages/factory/dist/twins/registry.js
+var TwinRegistry = class {
+	_twins = new Map();
+	/**
+	* Discovers and validates all *.yaml and *.yml twin definition files in the given directory.
+	* Non-recursive — only top-level files are processed.
+	*
+	* @throws {TwinDefinitionError} if a file contains invalid YAML or fails schema validation
+	* @throws {TwinRegistryError} if two files declare the same twin name
+	*/
+	async discover(dir) {
+		let entries;
+		try {
+			entries = await readdir$1(dir);
+		} catch (err) {
+			throw new TwinDefinitionError(`Failed to read directory: ${dir} — ${err.message}`);
+		}
+		const yamlFiles = entries.filter((f$1) => f$1.endsWith(".yaml") || f$1.endsWith(".yml"));
+		const perFileErrors = [];
+		for (const filename of yamlFiles) {
+			const filePath = resolve$1(join$1(dir, filename));
+			let raw;
+			try {
+				raw = await readFile$1(filePath, "utf-8");
+			} catch (err) {
+				perFileErrors.push(new TwinDefinitionError(`Failed to read file: ${filePath} — ${err.message}`, filePath));
+				continue;
+			}
+			let parsed;
+			try {
+				parsed = yaml.load(raw);
+			} catch (err) {
+				perFileErrors.push(new TwinDefinitionError(`Twin definition at ${filePath} contains invalid YAML: ${err.message}`, filePath));
+				continue;
+			}
+			const result = TwinDefinitionSchema.safeParse(parsed);
+			if (!result.success) {
+				const firstIssue = result.error.issues[0];
+				const fieldPath = firstIssue?.path?.join(".") ?? "unknown";
+				const fieldMessage = firstIssue?.message ?? result.error.message;
+				let message;
+				const issueCode = firstIssue?.code;
+				if (issueCode === "unrecognized_keys") {
+					const keys = firstIssue.keys ?? [];
+					message = `Twin definition at ${filePath} contains unrecognised field(s): ${keys.join(", ")}`;
+				} else if (issueCode === "unrecognized_key") {
+					const key = firstIssue.key ?? fieldPath;
+					message = `Twin definition at ${filePath} contains unrecognised field(s): ${key}`;
+				} else {
+					const parsedObj = parsed;
+					const isMissingField = parsedObj && typeof parsedObj === "object" && fieldPath !== "unknown" && !(fieldPath in parsedObj);
+					if (isMissingField) message = `Twin definition at ${filePath} is missing required field: ${fieldPath}`;
+					else message = `Twin definition at ${filePath} failed validation — ${fieldPath}: ${fieldMessage}`;
+				}
+				perFileErrors.push(new TwinDefinitionError(message, filePath));
+				continue;
+			}
+			const data = result.data;
+			const twin = {
+				name: data.name,
+				image: data.image,
+				ports: data.ports,
+				environment: data.environment,
+				sourceFile: filePath,
+				...data.healthcheck !== void 0 && { healthcheck: data.healthcheck }
+			};
+			if (this._twins.has(twin.name)) {
+				const existing = this._twins.get(twin.name);
+				throw new TwinRegistryError(`Duplicate twin name "${twin.name}" found in: ${existing.sourceFile} and ${filePath}`);
+			}
+			this._twins.set(twin.name, twin);
+		}
+		if (perFileErrors.length > 0) throw perFileErrors[0];
+	}
+	/**
+	* Returns all discovered twin definitions.
+	*/
+	list() {
+		return Array.from(this._twins.values());
+	}
+	/**
+	* Returns a twin definition by name, or undefined if not found.
+	*/
+	get(name) {
+		return this._twins.get(name);
+	}
+	/**
+	* Polls the health endpoint of a twin definition until healthy or timed out.
+	*
+	* @param twin - The twin definition to poll
+	* @param options - Optional overrides (e.g., mock fetch for testing)
+	* @returns HealthPollResult indicating success or timeout
+	*/
+	async pollHealth(twin, options) {
+		const { healthcheck } = twin;
+		if (!healthcheck) return {
+			healthy: true,
+			attempts: 0
+		};
+		const fetchFn = options?.fetch ?? globalThis.fetch;
+		const { url, interval_ms = 500, timeout_ms = 1e4 } = healthcheck;
+		const startTime = Date.now();
+		let attempts = 0;
+		while (true) {
+			attempts++;
+			try {
+				const response = await fetchFn(url);
+				if (response.ok) return {
+					healthy: true,
+					attempts
+				};
+			} catch {}
+			const elapsed = Date.now() - startTime;
+			if (elapsed >= timeout_ms) return {
+				healthy: false,
+				error: `Health check timed out after ${timeout_ms}ms`
+			};
+			await new Promise((resolve$2) => setTimeout(resolve$2, interval_ms));
+			if (Date.now() - startTime >= timeout_ms) return {
+				healthy: false,
+				error: `Health check timed out after ${timeout_ms}ms`
+			};
+		}
+	}
+};
+/**
+* Factory function that creates a new TwinRegistry instance.
+*/
+function createTwinRegistry() {
+	return new TwinRegistry();
+}
+
+//#endregion
+//#region packages/factory/dist/twins/docker-compose.js
+/**
+* Thrown when Docker is unavailable or the compose lifecycle fails.
+*/
+var TwinError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "TwinError";
+	}
+};
+/**
+* Generates a Docker Compose v3.8 YAML string from an array of twin definitions.
+* Built manually with template strings — no external YAML library required.
+*/
+function generateComposeYaml(twins) {
+	const lines = [];
+	lines.push("version: '3.8'");
+	lines.push("services:");
+	for (const twin of twins) {
+		lines.push(`  ${twin.name}:`);
+		lines.push(`    image: ${twin.image}`);
+		if (twin.ports.length > 0) {
+			lines.push("    ports:");
+			for (const port of twin.ports) lines.push(`      - "${port.host}:${port.container}"`);
+		}
+		if (twin.environment && Object.keys(twin.environment).length > 0) {
+			lines.push("    environment:");
+			for (const [key, value] of Object.entries(twin.environment)) lines.push(`      ${key}: ${value}`);
+		}
+	}
+	return lines.join("\n") + "\n";
+}
+/**
+* Polls a twin's health endpoint until it returns a 2xx response or exhausts attempts.
+*
+* Algorithm (from story 47-2 dev notes):
+*   attempts = 0
+*   while attempts < maxAttempts:
+*     try fetch → if ok, return
+*     catch (connection refused) → continue
+*     attempts++
+*     sleep(intervalMs)
+*   throw TwinError
+*/
+async function pollTwinHealth(twin, maxAttempts, healthIntervalMs) {
+	if (!twin.healthcheck?.url) return;
+	const url = twin.healthcheck.url;
+	const intervalMs = twin.healthcheck.interval_ms ?? healthIntervalMs;
+	let attempts = 0;
+	while (attempts < maxAttempts) {
+		try {
+			const response = await fetch(url);
+			if (response.ok) return;
+		} catch {}
+		attempts++;
+		if (attempts < maxAttempts) await new Promise((resolve$2) => setTimeout(resolve$2, intervalMs));
+	}
+	throw new TwinError(`Twin '${twin.name}' failed health check after ${maxAttempts} attempts`);
+}
+/**
+* Creates a TwinManager that orchestrates Docker Compose for digital twin services.
+*
+* The event bus is injected — do NOT import a global singleton or create one internally.
+*
+* @param eventBus - Typed event bus for emitting twin lifecycle events
+* @param options - Optional health check configuration
+* @returns TwinManager with start() and stop() methods
+*/
+function createTwinManager(eventBus, options) {
+	const maxHealthAttempts = options?.maxHealthAttempts ?? 30;
+	const healthIntervalMs = options?.healthIntervalMs ?? 1e3;
+	/** Temp directory containing the generated docker-compose.yml. Null when not started. */
+	let composeDir = null;
+	/** Twins that were passed to start() — used by stop() to emit twin:stopped events. */
+	let startedTwins = [];
+	return {
+		async start(twins) {
+			try {
+				execSync("docker info", { stdio: "ignore" });
+			} catch {
+				throw new TwinError("Docker not found — twins require Docker");
+			}
+			const yaml$1 = generateComposeYaml(twins);
+			const dir = join$1(tmpdir(), randomUUID());
+			mkdirSync(dir, { recursive: true });
+			writeFileSync(join$1(dir, "docker-compose.yml"), yaml$1, "utf-8");
+			composeDir = dir;
+			startedTwins = twins;
+			try {
+				execSync("docker compose up -d", {
+					cwd: dir,
+					stdio: "pipe"
+				});
+			} catch (err) {
+				const error = err;
+				const stderr = error.stderr?.toString() ?? "";
+				throw new TwinError(`docker compose up failed: ${stderr}`);
+			}
+			for (const twin of twins) await pollTwinHealth(twin, maxHealthAttempts, healthIntervalMs);
+			for (const twin of twins) eventBus.emit("twin:started", {
+				twinName: twin.name,
+				ports: twin.ports,
+				healthStatus: "healthy"
+			});
+		},
+		async stop() {
+			if (!composeDir) return;
+			const dir = composeDir;
+			try {
+				execSync("docker compose down --remove-orphans", {
+					cwd: dir,
+					stdio: "pipe"
+				});
+			} catch {}
+			rmSync(dir, {
+				recursive: true,
+				force: true
+			});
+			for (const twin of startedTwins) eventBus.emit("twin:stopped", { twinName: twin.name });
+			composeDir = null;
+			startedTwins = [];
+		},
+		getComposeDir() {
+			return composeDir;
+		}
+	};
+}
+
+//#endregion
+//#region packages/factory/dist/twins/templates.js
+/**
+* Twin Template Catalog — pre-built twin definition templates for common external services.
+*
+* Story 47-4.
+*/
+const localstackTemplate = {
+	name: "localstack",
+	description: "LocalStack — AWS cloud service emulator (S3, SQS, DynamoDB)",
+	definition: {
+		name: "localstack",
+		image: "localstack/localstack:latest",
+		ports: ["4566:4566"],
+		environment: { SERVICES: "s3,sqs,dynamodb" },
+		healthcheck: {
+			url: "http://localhost:4566/_localstack/health",
+			interval_ms: 500,
+			timeout_ms: 1e4
+		}
+	}
+};
+const wiremockTemplate = {
+	name: "wiremock",
+	description: "WireMock — HTTP API mock and stub server",
+	definition: {
+		name: "wiremock",
+		image: "wiremock/wiremock:latest",
+		ports: ["8080:8080"],
+		environment: {},
+		healthcheck: {
+			url: "http://localhost:8080/__admin/health",
+			interval_ms: 500,
+			timeout_ms: 1e4
+		}
+	}
+};
+/**
+* Map of all built-in twin templates, keyed by template name.
+*/
+const TWIN_TEMPLATES = new Map([[localstackTemplate.name, localstackTemplate], [wiremockTemplate.name, wiremockTemplate]]);
+/**
+* Returns all available twin template entries.
+*/
+function listTwinTemplates() {
+	return Array.from(TWIN_TEMPLATES.values());
+}
+/**
+* Returns the twin template entry for the given name, or `undefined` if not found.
+*/
+function getTwinTemplate(name) {
+	return TWIN_TEMPLATES.get(name);
+}
+
+//#endregion
+//#region packages/factory/dist/twins/run-state.js
+/**
+* Returns the absolute path to the run-state JSON file for the given project.
+*
+* @param projectDir - Absolute path to the project root (usually `process.cwd()`)
+*/
+function runStatePath(projectDir) {
+	return path.join(projectDir, ".substrate", "twins", ".run-state.json");
+}
+/**
+* Reads and JSON-parses the run-state file.
+*
+* @returns The parsed `TwinRunState`, or `null` if the file does not exist.
+* @throws If any I/O error other than ENOENT occurs, or if the JSON is invalid.
+*/
+async function readRunState(projectDir) {
+	const filePath = runStatePath(projectDir);
+	try {
+		const content = await readFile$1(filePath, "utf-8");
+		return JSON.parse(content);
+	} catch (err) {
+		if (err.code === "ENOENT") return null;
+		throw err;
+	}
+}
+/**
+* Writes the given run state to disk, creating parent directories as needed.
+*
+* @param projectDir - Absolute path to the project root
+* @param state - The `TwinRunState` to persist
+*/
+async function writeRunState(projectDir, state) {
+	const filePath = runStatePath(projectDir);
+	await mkdir$1(path.dirname(filePath), { recursive: true });
+	await writeFile$1(filePath, JSON.stringify(state, null, 2), "utf-8");
+}
+/**
+* Deletes the run-state file. No-op if the file does not exist.
+*
+* @param projectDir - Absolute path to the project root
+*/
+async function clearRunState(projectDir) {
+	const filePath = runStatePath(projectDir);
+	try {
+		await unlink(filePath);
+	} catch (err) {
+		if (err.code !== "ENOENT") throw err;
+	}
+}
+
+//#endregion
+//#region packages/factory/dist/twins/persistence.js
+/**
+* Retrieve all twin run summaries for a given run_id, with health failure counts.
+*
+* Uses two portable queries and merges results client-side.
+*
+* @returns Array of TwinRunSummary — empty array if no twins found for this run.
+*/
+async function getTwinRunsForRun(adapter, runId) {
+	const rows = await adapter.query("SELECT * FROM twin_runs WHERE run_id = ?", [runId]);
+	const failureCounts = await adapter.query("SELECT twin_name, COUNT(*) as cnt FROM twin_health_failures WHERE run_id = ? GROUP BY twin_name", [runId]);
+	const failureMap = new Map(failureCounts.map((r) => [r.twin_name, r.cnt]));
+	return rows.map((row) => ({
+		...row,
+		ports: row.ports_json ? JSON.parse(row.ports_json) : [],
+		health_failure_count: failureMap.get(row.twin_name) ?? 0
+	}));
+}
+
 //#endregion
 //#region packages/factory/dist/config.js
 /**
@@ -28500,7 +29029,7 @@ const FactoryConfigSchema = z.object({
 	scenario_dir: z.string().default(".substrate/scenarios/"),
 	satisfaction_threshold: z.number().min(0).max(1).default(.8),
 	budget_cap_usd: z.number().min(0).default(0),
-	wall_clock_cap_seconds: z.number().min(0).default(0),
+	wall_clock_cap_seconds: z.number().min(0).default(3600),
 	plateau_window: z.number().int().min(2).default(3),
 	plateau_threshold: z.number().min(0).max(1).default(.05),
 	backend: z.enum(["cli", "direct"]).default("cli"),
@@ -28610,6 +29139,27 @@ async function factorySchema(adapter) {
     )
   `);
 	await adapter.exec("CREATE INDEX IF NOT EXISTS idx_scenario_results_run ON scenario_results(run_id)");
+	await adapter.exec(`
+    CREATE TABLE IF NOT EXISTS twin_runs (
+      id          VARCHAR(255) PRIMARY KEY,
+      run_id      VARCHAR(255),
+      twin_name   TEXT NOT NULL,
+      started_at  DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+      stopped_at  DATETIME,
+      status      VARCHAR(32) NOT NULL DEFAULT 'running',
+      ports_json  TEXT
+    )
+  `);
+	await adapter.exec(`
+    CREATE TABLE IF NOT EXISTS twin_health_failures (
+      id            INTEGER PRIMARY KEY AUTOINCREMENT,
+      twin_name     TEXT NOT NULL,
+      run_id        VARCHAR(255),
+      checked_at    DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+      error_message TEXT NOT NULL
+    )
+  `);
+	await adapter.exec("CREATE INDEX IF NOT EXISTS idx_twin_health_failures_twin ON twin_health_failures(twin_name)");
 }
 
 //#endregion
@@ -28769,6 +29319,160 @@ function registerFactoryCommand(program) {
 		else process.stdout.write(`✗ ${passedCount}/${TOTAL_RULE_COUNT} rules passed, ${errors.length} ${errLabel}, ${warnings.length} ${warnLabel}\n`);
 		if (errors.length > 0) process.exit(1);
 	});
+	const twinsCmd = factoryCmd.command("twins").description("Digital twin template management");
+	twinsCmd.command("templates").description("List available built-in twin templates").action(() => {
+		const templates = listTwinTemplates();
+		for (const t of templates) process.stdout.write(`  ${t.name.padEnd(16)}  ${t.description}\n`);
+	});
+	twinsCmd.command("init").description("Initialize a twin definition file from a built-in template").requiredOption("--template <name>", "Template name (e.g. localstack, wiremock)").option("--force", "Overwrite existing file if it already exists").action(async (opts) => {
+		try {
+			const entry = getTwinTemplate(opts.template);
+			if (!entry) {
+				const available = listTwinTemplates().map((t) => t.name).join(", ");
+				process.stderr.write(`Error: Unknown template '${opts.template}'. Available: ${available}\n`);
+				process.exit(1);
+				return;
+			}
+			const targetPath = path.join(process.cwd(), ".substrate", "twins", `${opts.template}.yaml`);
+			if (!opts.force) try {
+				await access$1(targetPath);
+				process.stderr.write(`Error: File already exists: ${targetPath} — use --force to overwrite\n`);
+				process.exit(1);
+				return;
+			} catch {}
+			await mkdir$1(path.dirname(targetPath), { recursive: true });
+			const yamlContent = yaml.dump(entry.definition);
+			await writeFile$1(targetPath, yamlContent, "utf-8");
+			process.stdout.write(`Created ${targetPath}\n`);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			process.stderr.write(`Error: ${msg}\n`);
+			process.exit(1);
+		}
+	});
+	twinsCmd.command("start").description("Start all discovered twin definitions via Docker Compose").action(async () => {
+		try {
+			const projectDir = process.cwd();
+			const twinsDir = path.join(projectDir, ".substrate", "twins");
+			const registry = createTwinRegistry();
+			try {
+				await registry.discover(twinsDir);
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				process.stderr.write(`Error: ${msg}\n`);
+				process.exit(1);
+				return;
+			}
+			const twins = registry.list();
+			if (twins.length === 0) {
+				process.stderr.write("No twin definitions found in .substrate/twins/\n");
+				process.exit(1);
+				return;
+			}
+			const eventBus = new TypedEventBusImpl();
+			eventBus.on("twin:started", (e) => {
+				process.stdout.write(`  Started: ${e.twinName}\n`);
+			});
+			const manager = createTwinManager(eventBus);
+			try {
+				await manager.start(twins);
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				process.stderr.write(`Error: ${msg}\n`);
+				process.exit(1);
+				return;
+			}
+			const composeDir = manager.getComposeDir();
+			await writeRunState(projectDir, {
+				composeDir,
+				twinNames: twins.map((t) => t.name),
+				startedAt: new Date().toISOString()
+			});
+			process.stdout.write("\nAll twins started successfully.\n");
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			process.stderr.write(`Error: ${msg}\n`);
+			process.exit(1);
+		}
+	});
+	twinsCmd.command("stop").description("Stop all running twins").action(async () => {
+		try {
+			const projectDir = process.cwd();
+			const state = await readRunState(projectDir);
+			if (!state) {
+				process.stderr.write("No twins are currently running\n");
+				process.exit(1);
+				return;
+			}
+			try {
+				execSync("docker compose down --remove-orphans", {
+					cwd: state.composeDir,
+					stdio: "pipe"
+				});
+			} catch {}
+			rmSync(state.composeDir, {
+				recursive: true,
+				force: true
+			});
+			await clearRunState(projectDir);
+			process.stdout.write(`Stopped twins: ${state.twinNames.join(", ")}\n`);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			process.stderr.write(`Error: ${msg}\n`);
+			process.exit(1);
+		}
+	});
+	twinsCmd.command("status").description("Show status of all discovered twins").action(async () => {
+		try {
+			const projectDir = process.cwd();
+			const state = await readRunState(projectDir);
+			const runningNames = new Set(state?.twinNames ?? []);
+			const registry = createTwinRegistry();
+			let twins = [];
+			try {
+				await registry.discover(path.join(projectDir, ".substrate", "twins"));
+				twins = registry.list();
+			} catch {}
+			if (twins.length === 0) {
+				process.stdout.write("No twin definitions found in .substrate/twins/\n");
+				return;
+			}
+			for (const twin of twins) {
+				const status = runningNames.has(twin.name) ? "running" : "stopped";
+				const portsStr = twin.ports.length > 0 ? twin.ports.map((p) => `${p.host}:${p.container}`).join(", ") : "—";
+				process.stdout.write(`  ${twin.name.padEnd(20)}  ${status.padEnd(10)}  ${portsStr}\n`);
+			}
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			process.stderr.write(`Error: ${msg}\n`);
+			process.exit(1);
+		}
+	});
+	twinsCmd.command("list").description("List all discovered twin definitions").action(async () => {
+		try {
+			const projectDir = process.cwd();
+			const registry = createTwinRegistry();
+			let twins = [];
+			try {
+				await registry.discover(path.join(projectDir, ".substrate", "twins"));
+				twins = registry.list();
+			} catch {}
+			if (twins.length === 0) {
+				process.stdout.write("No twin definitions found in .substrate/twins/\n");
+				return;
+			}
+			process.stdout.write("  NAME                 IMAGE                                  PORTS           HEALTHCHECK\n");
+			for (const twin of twins) {
+				const ports = twin.ports.length > 0 ? twin.ports.map((p) => `${p.host}:${p.container}`).join(", ") : "—";
+				const healthcheck = twin.healthcheck?.url ?? "—";
+				process.stdout.write(`  ${twin.name.padEnd(20)}  ${twin.image.padEnd(38)}  ${ports.padEnd(16)}  ${healthcheck}\n`);
+			}
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			process.stderr.write(`Error: ${msg}\n`);
+			process.exit(1);
+		}
+	});
 }
 
 //#endregion
@@ -30243,5 +30947,5 @@ function registerRunCommand(program, _version = "0.0.0", projectRoot = process.c
 }
 
 //#endregion
-export { AdapterTelemetryPersistence, AppError, DoltRepoMapMetaRepository, DoltSymbolRepository, ERR_REPO_MAP_STORAGE_WRITE, GitClient, GrammarLoader, RepoMapInjector, RepoMapModule, RepoMapQueryEngine, RepoMapStorage, SymbolParser, createContextCompiler, createDispatcher, createEventEmitter, createImplementationOrchestrator, createPackLoader, createPhaseOrchestrator, createStopAfterGate, createTelemetryAdvisor, formatPhaseCompletionSummary, getFactoryRunSummaries, getScenarioResultsForRun, listGraphRuns, normalizeGraphSummaryToStatus, registerFactoryCommand, registerRunCommand, registerScenariosCommand, resolveStoryKeys, runAnalysisPhase, runPlanningPhase, runRunAction, runSolutioningPhase, validateStopAfterFromConflict };
-//# sourceMappingURL=run-bhGoAbu9.js.map
+export { AdapterTelemetryPersistence, AppError, DoltRepoMapMetaRepository, DoltSymbolRepository, ERR_REPO_MAP_STORAGE_WRITE, GitClient, GrammarLoader, RepoMapInjector, RepoMapModule, RepoMapQueryEngine, RepoMapStorage, SymbolParser, createContextCompiler, createDispatcher, createEventEmitter, createImplementationOrchestrator, createPackLoader, createPhaseOrchestrator, createStopAfterGate, createTelemetryAdvisor, formatPhaseCompletionSummary, getFactoryRunSummaries, getScenarioResultsForRun, getTwinRunsForRun, listGraphRuns, normalizeGraphSummaryToStatus, registerFactoryCommand, registerRunCommand, registerScenariosCommand, resolveStoryKeys, runAnalysisPhase, runPlanningPhase, runRunAction, runSolutioningPhase, validateStopAfterFromConflict };
+//# sourceMappingURL=run-z84Uu_U2.js.map

package/package.json

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