substrate-ai 0.3.0 → 0.3.2

package/dist/{run-DO9n3cwy.js → run-Fzhz3-mv.js}

@@ -1,5 +1,5 @@
 import { createLogger, deepMask } from "./logger-D2fS2ccL.js";
-import { CURRENT_CONFIG_FORMAT_VERSION, PartialSubstrateConfigSchema, SUPPORTED_CONFIG_FORMAT_VERSIONS, SubstrateConfigSchema, defaultConfigMigrator } from "./config-migrator-DSi8KhQC.js";
+import { CURRENT_CONFIG_FORMAT_VERSION, PartialSubstrateConfigSchema, SUPPORTED_CONFIG_FORMAT_VERSIONS, SubstrateConfigSchema, defaultConfigMigrator } from "./config-migrator-CQmBdKeG.js";
 import { ConfigError, ConfigIncompatibleFormatError, createEventBus, createTuiApp, isTuiCapable, printNonTtyWarning, sleep } from "./helpers-RL22dYtn.js";
 import { addTokenUsage, createDecision, createPipelineRun, createRequirement, getArtifactByTypeForRun, getArtifactsByRun, getDecisionsByCategory, getDecisionsByPhase, getDecisionsByPhaseForRun, getLatestRun, getPipelineRunById, getRunningPipelineRuns, getTokenUsageSummary, registerArtifact, updatePipelineRun, updatePipelineRunConfig, upsertDecision } from "./decisions-Dq4cAA2L.js";
 import { ADVISORY_NOTES, ESCALATION_DIAGNOSIS, OPERATIONAL_FINDING, STORY_METRICS, STORY_OUTCOME, TEST_EXPANSION_FINDING, TEST_PLAN, aggregateTokenUsageForRun, aggregateTokenUsageForStory, getStoryMetricsForRun, writeRunMetrics, writeStoryMetrics } from "./operational-Bovj4fS-.js";
@@ -19,6 +19,7 @@ import { existsSync as existsSync$1, readFileSync as readFileSync$1, readdirSync
 import { homedir } from "os";
 import { freemem, platform } from "node:os";
 import { createHash, randomUUID } from "node:crypto";
+import { createServer } from "node:http";
 
 //#region rolldown:runtime
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
@@ -605,7 +606,7 @@ const migration010RunMetrics = {
 
 //#endregion
 //#region src/persistence/migrations/index.ts
-const logger$23 = createLogger("persistence:migrations");
+const logger$25 = createLogger("persistence:migrations");
 const MIGRATIONS = [
 	initialSchemaMigration,
 	costTrackerSchemaMigration,
@@ -623,7 +624,7 @@ const MIGRATIONS = [
 * Safe to call multiple times — already-applied migrations are skipped.
 */
 function runMigrations(db) {
-	logger$23.info("Starting migration runner");
+	logger$25.info("Starting migration runner");
 	db.exec(`
     CREATE TABLE IF NOT EXISTS schema_migrations (
       version   INTEGER PRIMARY KEY,
@@ -634,12 +635,12 @@ function runMigrations(db) {
 	const appliedVersions = new Set(db.prepare("SELECT version FROM schema_migrations").all().map((row) => row.version));
 	const pending = MIGRATIONS.filter((m) => !appliedVersions.has(m.version)).sort((a, b) => a.version - b.version);
 	if (pending.length === 0) {
-		logger$23.info("No pending migrations");
+		logger$25.info("No pending migrations");
 		return;
 	}
 	const insertMigration = db.prepare("INSERT INTO schema_migrations (version, name) VALUES (?, ?)");
 	for (const migration of pending) {
-		logger$23.info({
+		logger$25.info({
 			version: migration.version,
 			name: migration.name
 		}, "Applying migration");
@@ -653,14 +654,14 @@ function runMigrations(db) {
 			});
 			applyMigration();
 		}
-		logger$23.info({ version: migration.version }, "Migration applied successfully");
+		logger$25.info({ version: migration.version }, "Migration applied successfully");
 	}
-	logger$23.info({ count: pending.length }, "All pending migrations applied");
+	logger$25.info({ count: pending.length }, "All pending migrations applied");
 }
 
 //#endregion
 //#region src/persistence/database.ts
-const logger$22 = createLogger("persistence:database");
+const logger$24 = createLogger("persistence:database");
 /**
 * Thin wrapper that opens a SQLite database, applies required PRAGMAs,
 * and exposes the raw BetterSqlite3 instance.
@@ -677,14 +678,14 @@ var DatabaseWrapper = class {
 	*/
 	open() {
 		if (this._db !== null) return;
-		logger$22.info({ path: this._path }, "Opening SQLite database");
+		logger$24.info({ path: this._path }, "Opening SQLite database");
 		this._db = new Database(this._path);
 		const walResult = this._db.pragma("journal_mode = WAL");
-		if (walResult?.[0]?.journal_mode !== "wal") logger$22.warn({ result: walResult?.[0]?.journal_mode }, "WAL pragma did not return expected \"wal\" — journal_mode may be \"memory\" or unsupported");
+		if (walResult?.[0]?.journal_mode !== "wal") logger$24.warn({ result: walResult?.[0]?.journal_mode }, "WAL pragma did not return expected \"wal\" — journal_mode may be \"memory\" or unsupported");
 		this._db.pragma("busy_timeout = 5000");
 		this._db.pragma("synchronous = NORMAL");
 		this._db.pragma("foreign_keys = ON");
-		logger$22.info({ path: this._path }, "SQLite database opened with WAL mode");
+		logger$24.info({ path: this._path }, "SQLite database opened with WAL mode");
 	}
 	/**
 	* Close the database. Idempotent — calling close() when already closed is a no-op.
@@ -693,7 +694,7 @@ var DatabaseWrapper = class {
 		if (this._db === null) return;
 		this._db.close();
 		this._db = null;
-		logger$22.info({ path: this._path }, "SQLite database closed");
+		logger$24.info({ path: this._path }, "SQLite database closed");
 	}
 	/**
 	* Return the raw BetterSqlite3 instance.
@@ -1610,7 +1611,7 @@ function formatUnsupportedVersionError(formatType, version, supported) {
 
 //#endregion
 //#region src/modules/config/config-system-impl.ts
-const logger$21 = createLogger("config");
+const logger$23 = createLogger("config");
 function deepMerge(base, override) {
 	const result = { ...base };
 	for (const [key, val] of Object.entries(override)) if (val !== null && val !== void 0 && typeof val === "object" && !Array.isArray(val) && typeof result[key] === "object" && result[key] !== null && !Array.isArray(result[key])) result[key] = deepMerge(result[key], val);
@@ -1655,7 +1656,7 @@ function readEnvOverrides() {
 	}
 	const parsed = PartialSubstrateConfigSchema.safeParse(overrides);
 	if (!parsed.success) {
-		logger$21.warn({ errors: parsed.error.issues }, "Invalid environment variable overrides ignored");
+		logger$23.warn({ errors: parsed.error.issues }, "Invalid environment variable overrides ignored");
 		return {};
 	}
 	return parsed.data;
@@ -1719,7 +1720,7 @@ var ConfigSystemImpl = class {
 			throw new ConfigError(`Configuration validation failed:\n${issues}`, { issues: result.error.issues });
 		}
 		this._config = result.data;
-		logger$21.debug("Configuration loaded successfully");
+		logger$23.debug("Configuration loaded successfully");
 	}
 	getConfig() {
 		if (this._config === null) throw new ConfigError("Configuration has not been loaded. Call load() before getConfig().", {});
@@ -1782,7 +1783,7 @@ var ConfigSystemImpl = class {
 				if (version !== void 0 && typeof version === "string" && !isVersionSupported(version, SUPPORTED_CONFIG_FORMAT_VERSIONS)) if (defaultConfigMigrator.canMigrate(version, CURRENT_CONFIG_FORMAT_VERSION)) {
 					const migrationOutput = defaultConfigMigrator.migrate(rawObj, version, CURRENT_CONFIG_FORMAT_VERSION, filePath);
 					if (migrationOutput.result.success) {
-						logger$21.info({
+						logger$23.info({
 							from: version,
 							to: CURRENT_CONFIG_FORMAT_VERSION,
 							backup: migrationOutput.result.backupPath
@@ -3191,7 +3192,7 @@ function truncateToTokens(text, maxTokens) {
 
 //#endregion
 //#region src/modules/context-compiler/context-compiler-impl.ts
-const logger$20 = createLogger("context-compiler");
+const logger$22 = createLogger("context-compiler");
 /**
 * Fraction of the original token budget that must remain (after required +
 * important sections) before an optional section is included.
@@ -3283,7 +3284,7 @@ var ContextCompilerImpl = class {
 				includedParts.push(truncated);
 				remainingBudget -= truncatedTokens;
 				anyTruncated = true;
-				logger$20.warn({
+				logger$22.warn({
 					section: section.name,
 					originalTokens: tokens,
 					budgetTokens: truncatedTokens
@@ -3297,7 +3298,7 @@ var ContextCompilerImpl = class {
 				});
 			} else {
 				anyTruncated = true;
-				logger$20.warn({
+				logger$22.warn({
 					section: section.name,
 					tokens
 				}, "Context compiler: omitted \"important\" section — no budget remaining");
@@ -3324,7 +3325,7 @@ var ContextCompilerImpl = class {
 				} else {
 					if (tokens > 0) {
 						anyTruncated = true;
-						logger$20.warn({
+						logger$22.warn({
 							section: section.name,
 							tokens,
 							budgetFractionRemaining: budgetFractionRemaining.toFixed(2)
@@ -3609,7 +3610,7 @@ function parseYamlResult(yamlText, schema) {
 
 //#endregion
 //#region src/modules/agent-dispatch/dispatcher-impl.ts
-const logger$19 = createLogger("agent-dispatch");
+const logger$21 = createLogger("agent-dispatch");
 const SHUTDOWN_GRACE_MS = 1e4;
 const SHUTDOWN_MAX_WAIT_MS = 3e4;
 const CHARS_PER_TOKEN = 4;
@@ -3654,7 +3655,7 @@ function getAvailableMemory() {
 			}).trim(), 10);
 			_lastKnownPressureLevel = pressureLevel;
 			if (pressureLevel >= 4) {
-				logger$19.warn({ pressureLevel }, "macOS kernel reports critical memory pressure");
+				logger$21.warn({ pressureLevel }, "macOS kernel reports critical memory pressure");
 				return 0;
 			}
 		} catch {}
@@ -3669,7 +3670,7 @@ function getAvailableMemory() {
 			const speculative = parseInt(vmstat.match(/Pages speculative:\s+(\d+)/)?.[1] ?? "0", 10);
 			const available = (free + purgeable + speculative) * pageSize;
 			if (pressureLevel >= 2) {
-				logger$19.warn({
+				logger$21.warn({
 					pressureLevel,
 					availableBeforeDiscount: available
 				}, "macOS kernel reports memory pressure — discounting estimate");
@@ -3749,7 +3750,7 @@ var DispatcherImpl = class {
 					resolve: typedResolve,
 					reject
 				});
-				logger$19.debug({
+				logger$21.debug({
 					id,
 					queueLength: this._queue.length
 				}, "Dispatch queued");
@@ -3780,7 +3781,7 @@ var DispatcherImpl = class {
 	async shutdown() {
 		this._shuttingDown = true;
 		this._stopMemoryPressureTimer();
-		logger$19.info({
+		logger$21.info({
 			running: this._running.size,
 			queued: this._queue.length
 		}, "Dispatcher shutting down");
@@ -3813,13 +3814,13 @@ var DispatcherImpl = class {
 				}
 			}, 50);
 		});
-		logger$19.info("Dispatcher shutdown complete");
+		logger$21.info("Dispatcher shutdown complete");
 	}
 	async _startDispatch(id, request, resolve$2) {
-		const { prompt, agent, taskType, timeout, outputSchema, workingDirectory, model, maxTurns } = request;
+		const { prompt, agent, taskType, timeout, outputSchema, workingDirectory, model, maxTurns, otlpEndpoint } = request;
 		const adapter = this._adapterRegistry.get(agent);
 		if (adapter === void 0) {
-			logger$19.warn({
+			logger$21.warn({
 				id,
 				agent
 			}, "No adapter found for agent");
@@ -3846,7 +3847,8 @@ var DispatcherImpl = class {
 			worktreePath,
 			billingMode: "subscription",
 			...model !== void 0 ? { model } : {},
-			...resolvedMaxTurns !== void 0 ? { maxTurns: resolvedMaxTurns } : {}
+			...resolvedMaxTurns !== void 0 ? { maxTurns: resolvedMaxTurns } : {},
+			...otlpEndpoint !== void 0 ? { otlpEndpoint } : {}
 		});
 		const timeoutMs = timeout ?? this._config.defaultTimeouts[taskType] ?? DEFAULT_TIMEOUTS[taskType] ?? 3e5;
 		const env = { ...process.env };
@@ -3865,7 +3867,7 @@ var DispatcherImpl = class {
 		});
 		const startedAt = Date.now();
 		proc.on("error", (err) => {
-			logger$19.error({
+			logger$21.error({
 				id,
 				binary: cmd.binary,
 				error: err.message
@@ -3873,7 +3875,7 @@ var DispatcherImpl = class {
 		});
 		if (proc.stdin !== null) {
 			proc.stdin.on("error", (err) => {
-				if (err.code !== "EPIPE") logger$19.warn({
+				if (err.code !== "EPIPE") logger$21.warn({
 					id,
 					error: err.message
 				}, "stdin write error");
@@ -3915,7 +3917,7 @@ var DispatcherImpl = class {
 			agent,
 			taskType
 		});
-		logger$19.debug({
+		logger$21.debug({
 			id,
 			agent,
 			taskType,
@@ -3932,7 +3934,7 @@ var DispatcherImpl = class {
 				dispatchId: id,
 				timeoutMs
 			});
-			logger$19.warn({
+			logger$21.warn({
 				id,
 				agent,
 				taskType,
@@ -3986,7 +3988,7 @@ var DispatcherImpl = class {
 					exitCode: code,
 					output: stdout
 				});
-				logger$19.debug({
+				logger$21.debug({
 					id,
 					agent,
 					taskType,
@@ -4012,7 +4014,7 @@ var DispatcherImpl = class {
 					error: stderr || `Process exited with code ${String(code)}`,
 					exitCode: code
 				});
-				logger$19.debug({
+				logger$21.debug({
 					id,
 					agent,
 					taskType,
@@ -4071,7 +4073,7 @@ var DispatcherImpl = class {
 		const next = this._queue.shift();
 		if (next === void 0) return;
 		next.handle.status = "running";
-		logger$19.debug({
+		logger$21.debug({
 			id: next.id,
 			queueLength: this._queue.length
 		}, "Dequeued dispatch");
@@ -4084,7 +4086,7 @@ var DispatcherImpl = class {
 	_isMemoryPressured() {
 		const free = getAvailableMemory();
 		if (free < MIN_FREE_MEMORY_BYTES) {
-			logger$19.warn({
+			logger$21.warn({
 				freeMB: Math.round(free / 1024 / 1024),
 				thresholdMB: Math.round(MIN_FREE_MEMORY_BYTES / 1024 / 1024),
 				pressureLevel: _lastKnownPressureLevel
@@ -4200,7 +4202,7 @@ function runBuildVerification(options) {
 	let cmd;
 	if (verifyCommand === void 0) {
 		const detection = detectPackageManager(projectRoot);
-		logger$19.info({
+		logger$21.info({
 			packageManager: detection.packageManager,
 			lockfile: detection.lockfile,
 			resolvedCommand: detection.command
@@ -4399,7 +4401,7 @@ function pickRecommendation(distribution, profile, totalIssues, reviewCycles, la
 
 //#endregion
 //#region src/modules/compiled-workflows/prompt-assembler.ts
-const logger$18 = createLogger("compiled-workflows:prompt-assembler");
+const logger$20 = createLogger("compiled-workflows:prompt-assembler");
 /**
 * Assemble a final prompt from a template and sections map.
 *
@@ -4424,7 +4426,7 @@ function assemblePrompt(template, sections, tokenCeiling = 2200) {
 		tokenCount,
 		truncated: false
 	};
-	logger$18.warn({
+	logger$20.warn({
 		tokenCount,
 		ceiling: tokenCeiling
 	}, "Prompt exceeds token ceiling — truncating optional sections");
@@ -4440,10 +4442,10 @@ function assemblePrompt(template, sections, tokenCeiling = 2200) {
 			const targetSectionTokens = Math.max(0, currentSectionTokens - overBy);
 			if (targetSectionTokens === 0) {
 				contentMap[section.name] = "";
-				logger$18.warn({ sectionName: section.name }, "Section eliminated to fit token budget");
+				logger$20.warn({ sectionName: section.name }, "Section eliminated to fit token budget");
 			} else {
 				contentMap[section.name] = truncateToTokens(section.content, targetSectionTokens);
-				logger$18.warn({
+				logger$20.warn({
 					sectionName: section.name,
 					targetSectionTokens
 				}, "Section truncated to fit token budget");
@@ -4454,7 +4456,7 @@ function assemblePrompt(template, sections, tokenCeiling = 2200) {
 		}
 		if (tokenCount <= tokenCeiling) break;
 	}
-	if (tokenCount > tokenCeiling) logger$18.warn({
+	if (tokenCount > tokenCeiling) logger$20.warn({
 		tokenCount,
 		ceiling: tokenCeiling
 	}, "Required sections alone exceed token ceiling — returning over-budget prompt");
@@ -4752,7 +4754,7 @@ function getTokenCeiling(workflowType, tokenCeilings) {
 
 //#endregion
 //#region src/modules/compiled-workflows/create-story.ts
-const logger$17 = createLogger("compiled-workflows:create-story");
+const logger$19 = createLogger("compiled-workflows:create-story");
 /**
 * Execute the compiled create-story workflow.
 *
@@ -4772,13 +4774,13 @@ const logger$17 = createLogger("compiled-workflows:create-story");
 */
 async function runCreateStory(deps, params) {
 	const { epicId, storyKey, pipelineRunId } = params;
-	logger$17.debug({
+	logger$19.debug({
 		epicId,
 		storyKey,
 		pipelineRunId
 	}, "Starting create-story workflow");
 	const { ceiling: TOKEN_CEILING, source: tokenCeilingSource } = getTokenCeiling("create-story", deps.tokenCeilings);
-	logger$17.info({
+	logger$19.info({
 		workflow: "create-story",
 		ceiling: TOKEN_CEILING,
 		source: tokenCeilingSource
@@ -4788,7 +4790,7 @@ async function runCreateStory(deps, params) {
 		template = await deps.pack.getPrompt("create-story");
 	} catch (err) {
 		const error = err instanceof Error ? err.message : String(err);
-		logger$17.error({ error }, "Failed to retrieve create-story prompt template");
+		logger$19.error({ error }, "Failed to retrieve create-story prompt template");
 		return {
 			result: "failed",
 			error: `Failed to retrieve prompt template: ${error}`,
@@ -4830,7 +4832,7 @@ async function runCreateStory(deps, params) {
 			priority: "important"
 		}
 	], TOKEN_CEILING);
-	logger$17.debug({
+	logger$19.debug({
 		tokenCount,
 		truncated,
 		tokenCeiling: TOKEN_CEILING
@@ -4840,14 +4842,15 @@ async function runCreateStory(deps, params) {
 		agent: "claude-code",
 		taskType: "create-story",
 		outputSchema: CreateStoryResultSchema,
-		...deps.projectRoot !== void 0 ? { workingDirectory: deps.projectRoot } : {}
+		...deps.projectRoot !== void 0 ? { workingDirectory: deps.projectRoot } : {},
+		...deps.otlpEndpoint !== void 0 ? { otlpEndpoint: deps.otlpEndpoint } : {}
 	});
 	let dispatchResult;
 	try {
 		dispatchResult = await handle.result;
 	} catch (err) {
 		const error = err instanceof Error ? err.message : String(err);
-		logger$17.error({
+		logger$19.error({
 			epicId,
 			storyKey,
 			error
@@ -4868,7 +4871,7 @@ async function runCreateStory(deps, params) {
 	if (dispatchResult.status === "failed") {
 		const errorMsg = dispatchResult.parseError ?? `Dispatch failed with exit code ${dispatchResult.exitCode}`;
 		const stderrDetail = dispatchResult.output ? ` Output: ${dispatchResult.output}` : "";
-		logger$17.warn({
+		logger$19.warn({
 			epicId,
 			storyKey,
 			exitCode: dispatchResult.exitCode
@@ -4880,7 +4883,7 @@ async function runCreateStory(deps, params) {
 		};
 	}
 	if (dispatchResult.status === "timeout") {
-		logger$17.warn({
+		logger$19.warn({
 			epicId,
 			storyKey
 		}, "Create-story dispatch timed out");
@@ -4893,7 +4896,7 @@ async function runCreateStory(deps, params) {
 	if (dispatchResult.parsed === null) {
 		const details = dispatchResult.parseError ?? "No YAML block found in output";
 		const rawSnippet = dispatchResult.output ? dispatchResult.output.slice(0, 1e3) : "(empty)";
-		logger$17.warn({
+		logger$19.warn({
 			epicId,
 			storyKey,
 			details,
@@ -4909,7 +4912,7 @@ async function runCreateStory(deps, params) {
 	const parseResult = CreateStoryResultSchema.safeParse(dispatchResult.parsed);
 	if (!parseResult.success) {
 		const details = parseResult.error.message;
-		logger$17.warn({
+		logger$19.warn({
 			epicId,
 			storyKey,
 			details
@@ -4922,7 +4925,7 @@ async function runCreateStory(deps, params) {
 		};
 	}
 	const parsed = parseResult.data;
-	logger$17.info({
+	logger$19.info({
 		epicId,
 		storyKey,
 		storyFile: parsed.story_file,
@@ -4944,7 +4947,7 @@ function getImplementationDecisions(deps) {
 	try {
 		return getDecisionsByPhase(deps.db, "implementation");
 	} catch (err) {
-		logger$17.warn({ error: err instanceof Error ? err.message : String(err) }, "Failed to retrieve implementation decisions");
+		logger$19.warn({ error: err instanceof Error ? err.message : String(err) }, "Failed to retrieve implementation decisions");
 		return [];
 	}
 }
@@ -4987,13 +4990,13 @@ function getEpicShard(decisions, epicId, projectRoot, storyKey) {
 			if (storyKey) {
 				const storySection = extractStorySection(shardContent, storyKey);
 				if (storySection) {
-					logger$17.debug({
+					logger$19.debug({
 						epicId,
 						storyKey
 					}, "Extracted per-story section from epic shard");
 					return storySection;
 				}
-				logger$17.debug({
+				logger$19.debug({
 					epicId,
 					storyKey
 				}, "No matching story section found — using full epic shard");
@@ -5003,11 +5006,11 @@ function getEpicShard(decisions, epicId, projectRoot, storyKey) {
 		if (projectRoot) {
 			const fallback = readEpicShardFromFile(projectRoot, epicId);
 			if (fallback) {
-				logger$17.info({ epicId }, "Using file-based fallback for epic shard (decisions table empty)");
+				logger$19.info({ epicId }, "Using file-based fallback for epic shard (decisions table empty)");
 				if (storyKey) {
 					const storySection = extractStorySection(fallback, storyKey);
 					if (storySection) {
-						logger$17.debug({
+						logger$19.debug({
 							epicId,
 							storyKey
 						}, "Extracted per-story section from file-based epic shard");
@@ -5019,7 +5022,7 @@ function getEpicShard(decisions, epicId, projectRoot, storyKey) {
 		}
 		return "";
 	} catch (err) {
-		logger$17.warn({
+		logger$19.warn({
 			epicId,
 			error: err instanceof Error ? err.message : String(err)
 		}, "Failed to retrieve epic shard");
@@ -5036,7 +5039,7 @@ function getPrevDevNotes(decisions, epicId) {
 		if (devNotes.length === 0) return "";
 		return devNotes[devNotes.length - 1].value;
 	} catch (err) {
-		logger$17.warn({
+		logger$19.warn({
 			epicId,
 			error: err instanceof Error ? err.message : String(err)
 		}, "Failed to retrieve prev dev notes");
@@ -5056,13 +5059,13 @@ function getArchConstraints$3(deps) {
 		if (deps.projectRoot) {
 			const fallback = readArchConstraintsFromFile(deps.projectRoot);
 			if (fallback) {
-				logger$17.info("Using file-based fallback for architecture constraints (decisions table empty)");
+				logger$19.info("Using file-based fallback for architecture constraints (decisions table empty)");
 				return fallback;
 			}
 		}
 		return "";
 	} catch (err) {
-		logger$17.warn({ error: err instanceof Error ? err.message : String(err) }, "Failed to retrieve architecture constraints");
+		logger$19.warn({ error: err instanceof Error ? err.message : String(err) }, "Failed to retrieve architecture constraints");
 		return "";
 	}
 }
@@ -5082,7 +5085,7 @@ function readEpicShardFromFile(projectRoot, epicId) {
 		const match = pattern.exec(content);
 		return match ? match[0].trim() : "";
 	} catch (err) {
-		logger$17.warn({
+		logger$19.warn({
 			epicId,
 			error: err instanceof Error ? err.message : String(err)
 		}, "File-based epic shard fallback failed");
@@ -5105,7 +5108,7 @@ function readArchConstraintsFromFile(projectRoot) {
 		const content = readFileSync$1(archPath, "utf-8");
 		return content.slice(0, 1500);
 	} catch (err) {
-		logger$17.warn({ error: err instanceof Error ? err.message : String(err) }, "File-based architecture fallback failed");
+		logger$19.warn({ error: err instanceof Error ? err.message : String(err) }, "File-based architecture fallback failed");
 		return "";
 	}
 }
@@ -5118,7 +5121,7 @@ async function getStoryTemplate(deps) {
 	try {
 		return await deps.pack.getTemplate("story");
 	} catch (err) {
-		logger$17.warn({ error: err instanceof Error ? err.message : String(err) }, "Failed to retrieve story template from pack");
+		logger$19.warn({ error: err instanceof Error ? err.message : String(err) }, "Failed to retrieve story template from pack");
 		return "";
 	}
 }
@@ -5155,7 +5158,7 @@ async function isValidStoryFile(filePath) {
 
 //#endregion
 //#region src/modules/compiled-workflows/git-helpers.ts
-const logger$16 = createLogger("compiled-workflows:git-helpers");
+const logger$18 = createLogger("compiled-workflows:git-helpers");
 /**
 * Capture the full git diff for HEAD (working tree vs current commit).
 *
@@ -5251,7 +5254,7 @@ async function stageIntentToAdd(files, workingDirectory) {
 	if (files.length === 0) return;
 	const existing = files.filter((f) => {
 		const exists = existsSync$1(f);
-		if (!exists) logger$16.debug({ file: f }, "Skipping nonexistent file in stageIntentToAdd");
+		if (!exists) logger$18.debug({ file: f }, "Skipping nonexistent file in stageIntentToAdd");
 		return exists;
 	});
 	if (existing.length === 0) return;
@@ -5285,7 +5288,7 @@ async function runGitCommand(args, cwd, logLabel) {
 			stderr += chunk.toString("utf-8");
 		});
 		proc.on("error", (err) => {
-			logger$16.warn({
+			logger$18.warn({
 				label: logLabel,
 				cwd,
 				error: err.message
@@ -5294,7 +5297,7 @@ async function runGitCommand(args, cwd, logLabel) {
 		});
 		proc.on("close", (code) => {
 			if (code !== 0) {
-				logger$16.warn({
+				logger$18.warn({
 					label: logLabel,
 					cwd,
 					code,
@@ -5310,7 +5313,7 @@ async function runGitCommand(args, cwd, logLabel) {
 
 //#endregion
 //#region src/modules/implementation-orchestrator/project-findings.ts
-const logger$15 = createLogger("project-findings");
+const logger$17 = createLogger("project-findings");
 /** Maximum character length for the findings summary */
 const MAX_CHARS = 2e3;
 /**
@@ -5376,7 +5379,7 @@ function getProjectFindings(db) {
 		if (summary.length > MAX_CHARS) summary = summary.slice(0, MAX_CHARS - 3) + "...";
 		return summary;
 	} catch (err) {
-		logger$15.warn({ err }, "Failed to query project findings (graceful fallback)");
+		logger$17.warn({ err }, "Failed to query project findings (graceful fallback)");
 		return "";
 	}
 }
@@ -5399,7 +5402,7 @@ function extractRecurringPatterns(outcomes) {
 
 //#endregion
 //#region src/modules/compiled-workflows/story-complexity.ts
-const logger$14 = createLogger("compiled-workflows:story-complexity");
+const logger$16 = createLogger("compiled-workflows:story-complexity");
 /**
 * Compute a complexity score from story markdown content.
 *
@@ -5451,7 +5454,7 @@ function resolveFixStoryMaxTurns(complexityScore) {
 * @param resolvedMaxTurns - Turn limit resolved for this dispatch
 */
 function logComplexityResult(storyKey, complexity, resolvedMaxTurns) {
-	logger$14.info({
+	logger$16.info({
 		storyKey,
 		taskCount: complexity.taskCount,
 		subtaskCount: complexity.subtaskCount,
@@ -5509,7 +5512,7 @@ function countFilesInLayout(content) {
 
 //#endregion
 //#region src/modules/compiled-workflows/dev-story.ts
-const logger$13 = createLogger("compiled-workflows:dev-story");
+const logger$15 = createLogger("compiled-workflows:dev-story");
 /** Default timeout for dev-story dispatches in milliseconds (30 min) */
 const DEFAULT_TIMEOUT_MS$1 = 18e5;
 /** Default Vitest test patterns injected when no test-pattern decisions exist */
@@ -5532,12 +5535,12 @@ const DEFAULT_VITEST_PATTERNS = `## Test Patterns (defaults)
 */
 async function runDevStory(deps, params) {
 	const { storyKey, storyFilePath, taskScope, priorFiles } = params;
-	logger$13.info({
+	logger$15.info({
 		storyKey,
 		storyFilePath
 	}, "Starting compiled dev-story workflow");
 	const { ceiling: TOKEN_CEILING, source: tokenCeilingSource } = getTokenCeiling("dev-story", deps.tokenCeilings);
-	logger$13.info({
+	logger$15.info({
 		workflow: "dev-story",
 		ceiling: TOKEN_CEILING,
 		source: tokenCeilingSource
@@ -5580,10 +5583,10 @@ async function runDevStory(deps, params) {
 	let template;
 	try {
 		template = await deps.pack.getPrompt("dev-story");
-		logger$13.debug({ storyKey }, "Retrieved dev-story prompt template from pack");
+		logger$15.debug({ storyKey }, "Retrieved dev-story prompt template from pack");
 	} catch (err) {
 		const error = err instanceof Error ? err.message : String(err);
-		logger$13.error({
+		logger$15.error({
 			storyKey,
 			error
 		}, "Failed to retrieve dev-story prompt template");
@@ -5594,14 +5597,14 @@ async function runDevStory(deps, params) {
 		storyContent = await readFile$1(storyFilePath, "utf-8");
 	} catch (err) {
 		if (err.code === "ENOENT") {
-			logger$13.error({
+			logger$15.error({
 				storyKey,
 				storyFilePath
 			}, "Story file not found");
 			return makeFailureResult("story_file_not_found");
 		}
 		const error = err instanceof Error ? err.message : String(err);
-		logger$13.error({
+		logger$15.error({
 			storyKey,
 			storyFilePath,
 			error
@@ -5609,7 +5612,7 @@ async function runDevStory(deps, params) {
 		return makeFailureResult(`story_file_read_error: ${error}`);
 	}
 	if (storyContent.trim().length === 0) {
-		logger$13.error({
+		logger$15.error({
 			storyKey,
 			storyFilePath
 		}, "Story file is empty");
@@ -5624,17 +5627,17 @@ async function runDevStory(deps, params) {
 		const testPatternDecisions = solutioningDecisions.filter((d) => d.category === "test-patterns");
 		if (testPatternDecisions.length > 0) {
 			testPatternsContent = "## Test Patterns\n" + testPatternDecisions.map((d) => `- ${d.key}: ${d.value}`).join("\n");
-			logger$13.debug({
+			logger$15.debug({
 				storyKey,
 				count: testPatternDecisions.length
 			}, "Loaded test patterns from decision store");
 		} else {
 			testPatternsContent = DEFAULT_VITEST_PATTERNS;
-			logger$13.debug({ storyKey }, "No test-pattern decisions found — using default Vitest patterns");
+			logger$15.debug({ storyKey }, "No test-pattern decisions found — using default Vitest patterns");
 		}
 	} catch (err) {
 		const error = err instanceof Error ? err.message : String(err);
-		logger$13.warn({
+		logger$15.warn({
 			storyKey,
 			error
 		}, "Failed to load test patterns — using defaults");
@@ -5649,7 +5652,7 @@ async function runDevStory(deps, params) {
 		const findings = getProjectFindings(deps.db);
 		if (findings.length > 0) {
 			priorFindingsContent = "Previous pipeline runs encountered these issues — avoid repeating them:\n\n" + findings;
-			logger$13.debug({
+			logger$15.debug({
 				storyKey,
 				findingsLen: findings.length
 			}, "Injecting prior findings into dev-story prompt");
@@ -5669,7 +5672,7 @@ async function runDevStory(deps, params) {
 			if (plan.test_categories && plan.test_categories.length > 0) parts.push(`\n### Categories: ${plan.test_categories.join(", ")}`);
 			if (plan.coverage_notes) parts.push(`\n### Coverage Notes\n${plan.coverage_notes}`);
 			testPlanContent = parts.join("\n");
-			logger$13.debug({ storyKey }, "Injecting test plan into dev-story prompt");
+			logger$15.debug({ storyKey }, "Injecting test plan into dev-story prompt");
 		}
 	} catch {}
 	const sections = [
@@ -5715,7 +5718,7 @@ async function runDevStory(deps, params) {
 		}
 	];
 	const { prompt, tokenCount, truncated } = assemblePrompt(template, sections, TOKEN_CEILING);
-	logger$13.info({
+	logger$15.info({
 		storyKey,
 		tokenCount,
 		ceiling: TOKEN_CEILING,
@@ -5730,12 +5733,13 @@ async function runDevStory(deps, params) {
 			timeout: DEFAULT_TIMEOUT_MS$1,
 			outputSchema: DevStoryResultSchema,
 			maxTurns: resolvedMaxTurns,
-			...deps.projectRoot !== void 0 ? { workingDirectory: deps.projectRoot } : {}
+			...deps.projectRoot !== void 0 ? { workingDirectory: deps.projectRoot } : {},
+			...deps.otlpEndpoint !== void 0 ? { otlpEndpoint: deps.otlpEndpoint } : {}
 		});
 		dispatchResult = await handle.result;
 	} catch (err) {
 		const error = err instanceof Error ? err.message : String(err);
-		logger$13.error({
+		logger$15.error({
 			storyKey,
 			error
 		}, "Dispatch threw an unexpected error");
@@ -5746,11 +5750,11 @@ async function runDevStory(deps, params) {
 		output: dispatchResult.tokenEstimate.output
 	};
 	if (dispatchResult.status === "timeout") {
-		logger$13.error({
+		logger$15.error({
 			storyKey,
 			durationMs: dispatchResult.durationMs
 		}, "Dev-story dispatch timed out");
-		if (dispatchResult.output.length > 0) logger$13.info({
+		if (dispatchResult.output.length > 0) logger$15.info({
 			storyKey,
 			partialOutput: dispatchResult.output.slice(0, 500)
 		}, "Partial output before timeout");
@@ -5760,12 +5764,12 @@ async function runDevStory(deps, params) {
 		};
 	}
 	if (dispatchResult.status === "failed" || dispatchResult.exitCode !== 0) {
-		logger$13.error({
+		logger$15.error({
 			storyKey,
 			exitCode: dispatchResult.exitCode,
 			status: dispatchResult.status
 		}, "Dev-story dispatch failed");
-		if (dispatchResult.output.length > 0) logger$13.info({
+		if (dispatchResult.output.length > 0) logger$15.info({
 			storyKey,
 			partialOutput: dispatchResult.output.slice(0, 500)
 		}, "Partial output from failed dispatch");
@@ -5777,7 +5781,7 @@ async function runDevStory(deps, params) {
 	if (dispatchResult.parseError !== null || dispatchResult.parsed === null) {
 		const details = dispatchResult.parseError ?? "parsed result was null";
 		const rawSnippet = dispatchResult.output ? dispatchResult.output.slice(0, 1e3) : "(empty)";
-		logger$13.error({
+		logger$15.error({
 			storyKey,
 			parseError: details,
 			rawOutputSnippet: rawSnippet
@@ -5785,12 +5789,12 @@ async function runDevStory(deps, params) {
 		let filesModified = [];
 		try {
 			filesModified = await getGitChangedFiles(deps.projectRoot ?? process.cwd());
-			if (filesModified.length > 0) logger$13.info({
+			if (filesModified.length > 0) logger$15.info({
 				storyKey,
 				fileCount: filesModified.length
 			}, "Recovered files_modified from git status (YAML fallback)");
 		} catch (err) {
-			logger$13.warn({
+			logger$15.warn({
 				storyKey,
 				error: err instanceof Error ? err.message : String(err)
 			}, "Failed to recover files_modified from git");
@@ -5807,7 +5811,7 @@ async function runDevStory(deps, params) {
 		};
 	}
 	const parsed = dispatchResult.parsed;
-	logger$13.info({
+	logger$15.info({
 		storyKey,
 		result: parsed.result,
 		acMet: parsed.ac_met.length
@@ -5946,7 +5950,7 @@ function extractFilesInScope(storyContent) {
 
 //#endregion
 //#region src/modules/compiled-workflows/code-review.ts
-const logger$12 = createLogger("compiled-workflows:code-review");
+const logger$14 = createLogger("compiled-workflows:code-review");
 /**
 * Default fallback result when dispatch fails or times out.
 * Uses NEEDS_MINOR_FIXES (not NEEDS_MAJOR_REWORK) so a parse/schema failure
@@ -5984,14 +5988,14 @@ function defaultFailResult(error, tokenUsage) {
 async function runCodeReview(deps, params) {
 	const { storyKey, storyFilePath, workingDirectory, pipelineRunId, filesModified, previousIssues } = params;
 	const cwd = workingDirectory ?? process.cwd();
-	logger$12.debug({
+	logger$14.debug({
 		storyKey,
 		storyFilePath,
 		cwd,
 		pipelineRunId
 	}, "Starting code-review workflow");
 	const { ceiling: TOKEN_CEILING, source: tokenCeilingSource } = getTokenCeiling("code-review", deps.tokenCeilings);
-	logger$12.info({
+	logger$14.info({
 		workflow: "code-review",
 		ceiling: TOKEN_CEILING,
 		source: tokenCeilingSource
@@ -6001,7 +6005,7 @@ async function runCodeReview(deps, params) {
 		template = await deps.pack.getPrompt("code-review");
 	} catch (err) {
 		const error = err instanceof Error ? err.message : String(err);
-		logger$12.error({ error }, "Failed to retrieve code-review prompt template");
+		logger$14.error({ error }, "Failed to retrieve code-review prompt template");
 		return defaultFailResult(`Failed to retrieve prompt template: ${error}`, {
 			input: 0,
 			output: 0
@@ -6012,7 +6016,7 @@ async function runCodeReview(deps, params) {
 		storyContent = await readFile$1(storyFilePath, "utf-8");
 	} catch (err) {
 		const error = err instanceof Error ? err.message : String(err);
-		logger$12.error({
+		logger$14.error({
 			storyFilePath,
 			error
 		}, "Failed to read story file");
@@ -6032,12 +6036,12 @@ async function runCodeReview(deps, params) {
 		const scopedTotal = nonDiffTokens + countTokens(scopedDiff);
 		if (scopedTotal <= TOKEN_CEILING) {
 			gitDiffContent = scopedDiff;
-			logger$12.debug({
+			logger$14.debug({
 				fileCount: filesModified.length,
 				tokenCount: scopedTotal
 			}, "Using scoped file diff");
 		} else {
-			logger$12.warn({
+			logger$14.warn({
 				estimatedTotal: scopedTotal,
 				ceiling: TOKEN_CEILING,
 				fileCount: filesModified.length
@@ -6051,7 +6055,7 @@ async function runCodeReview(deps, params) {
 		const fullTotal = nonDiffTokens + countTokens(fullDiff);
 		if (fullTotal <= TOKEN_CEILING) gitDiffContent = fullDiff;
 		else {
-			logger$12.warn({
+			logger$14.warn({
 				estimatedTotal: fullTotal,
 				ceiling: TOKEN_CEILING
 			}, "Full git diff would exceed token ceiling — using stat-only summary");
@@ -6059,7 +6063,7 @@ async function runCodeReview(deps, params) {
 		}
 	}
 	if (gitDiffContent.trim().length === 0) {
-		logger$12.info({ storyKey }, "Empty git diff — skipping review with SHIP_IT");
+		logger$14.info({ storyKey }, "Empty git diff — skipping review with SHIP_IT");
 		return {
 			verdict: "SHIP_IT",
 			issues: 0,
@@ -6084,7 +6088,7 @@ async function runCodeReview(deps, params) {
 		const findings = getProjectFindings(deps.db);
 		if (findings.length > 0) {
 			priorFindingsContent = "Previous reviews found these recurring patterns — pay special attention:\n\n" + findings;
-			logger$12.debug({
+			logger$14.debug({
 				storyKey,
 				findingsLen: findings.length
 			}, "Injecting prior findings into code-review prompt");
@@ -6118,11 +6122,11 @@ async function runCodeReview(deps, params) {
 		}
 	];
 	const assembleResult = assemblePrompt(template, sections, TOKEN_CEILING);
-	if (assembleResult.truncated) logger$12.warn({
+	if (assembleResult.truncated) logger$14.warn({
 		storyKey,
 		tokenCount: assembleResult.tokenCount
 	}, "Code-review prompt truncated to fit token ceiling");
-	logger$12.debug({
+	logger$14.debug({
 		storyKey,
 		tokenCount: assembleResult.tokenCount,
 		truncated: assembleResult.truncated
@@ -6133,14 +6137,15 @@ async function runCodeReview(deps, params) {
 		agent: "claude-code",
 		taskType: "code-review",
 		outputSchema: CodeReviewResultSchema,
-		workingDirectory: deps.projectRoot
+		workingDirectory: deps.projectRoot,
+		...deps.otlpEndpoint !== void 0 ? { otlpEndpoint: deps.otlpEndpoint } : {}
 	});
 	let dispatchResult;
 	try {
 		dispatchResult = await handle.result;
 	} catch (err) {
 		const error = err instanceof Error ? err.message : String(err);
-		logger$12.error({
+		logger$14.error({
 			storyKey,
 			error
 		}, "Code-review dispatch threw unexpected error");
@@ -6156,7 +6161,7 @@ async function runCodeReview(deps, params) {
 	const rawOutput = dispatchResult.output ?? void 0;
 	if (dispatchResult.status === "failed") {
 		const errorMsg = `Dispatch status: failed. Exit code: ${dispatchResult.exitCode}. ${dispatchResult.parseError ?? ""} ${dispatchResult.output ? `Stderr: ${dispatchResult.output}` : ""}`.trim();
-		logger$12.warn({
+		logger$14.warn({
 			storyKey,
 			exitCode: dispatchResult.exitCode
 		}, "Code-review dispatch failed");
@@ -6166,7 +6171,7 @@ async function runCodeReview(deps, params) {
 		};
 	}
 	if (dispatchResult.status === "timeout") {
-		logger$12.warn({ storyKey }, "Code-review dispatch timed out");
+		logger$14.warn({ storyKey }, "Code-review dispatch timed out");
 		return {
 			...defaultFailResult("Dispatch status: timeout. The agent did not complete within the allowed time.", tokenUsage),
 			rawOutput
@@ -6174,7 +6179,7 @@ async function runCodeReview(deps, params) {
 	}
 	if (dispatchResult.parsed === null) {
 		const details = dispatchResult.parseError ?? "No YAML block found in output";
-		logger$12.warn({
+		logger$14.warn({
 			storyKey,
 			details
 		}, "Code-review output schema validation failed");
@@ -6191,7 +6196,7 @@ async function runCodeReview(deps, params) {
 	const parseResult = CodeReviewResultSchema.safeParse(dispatchResult.parsed);
 	if (!parseResult.success) {
 		const details = parseResult.error.message;
-		logger$12.warn({
+		logger$14.warn({
 			storyKey,
 			details
 		}, "Code-review output failed schema validation");
@@ -6206,13 +6211,13 @@ async function runCodeReview(deps, params) {
 		};
 	}
 	const parsed = parseResult.data;
-	if (parsed.agentVerdict !== parsed.verdict) logger$12.info({
+	if (parsed.agentVerdict !== parsed.verdict) logger$14.info({
 		storyKey,
 		agentVerdict: parsed.agentVerdict,
 		pipelineVerdict: parsed.verdict,
 		issues: parsed.issues
 	}, "Pipeline overrode agent verdict based on issue severities");
-	logger$12.info({
+	logger$14.info({
 		storyKey,
 		verdict: parsed.verdict,
 		issues: parsed.issues
@@ -6237,14 +6242,14 @@ function getArchConstraints$2(deps) {
 		if (constraints.length === 0) return "";
 		return constraints.map((d) => `${d.key}: ${d.value}`).join("\n");
 	} catch (err) {
-		logger$12.warn({ error: err instanceof Error ? err.message : String(err) }, "Failed to retrieve architecture constraints");
+		logger$14.warn({ error: err instanceof Error ? err.message : String(err) }, "Failed to retrieve architecture constraints");
 		return "";
 	}
 }
 
 //#endregion
 //#region src/modules/compiled-workflows/test-plan.ts
-const logger$11 = createLogger("compiled-workflows:test-plan");
+const logger$13 = createLogger("compiled-workflows:test-plan");
 /** Default timeout for test-plan dispatches in milliseconds (5 min — lightweight call) */
 const DEFAULT_TIMEOUT_MS = 3e5;
 /**
@@ -6256,12 +6261,12 @@ const DEFAULT_TIMEOUT_MS = 3e5;
 */
 async function runTestPlan(deps, params) {
 	const { storyKey, storyFilePath, pipelineRunId } = params;
-	logger$11.info({
+	logger$13.info({
 		storyKey,
 		storyFilePath
 	}, "Starting compiled test-plan workflow");
 	const { ceiling: TOKEN_CEILING, source: tokenCeilingSource } = getTokenCeiling("test-plan", deps.tokenCeilings);
-	logger$11.info({
+	logger$13.info({
 		workflow: "test-plan",
 		ceiling: TOKEN_CEILING,
 		source: tokenCeilingSource
@@ -6269,10 +6274,10 @@ async function runTestPlan(deps, params) {
 	let template;
 	try {
 		template = await deps.pack.getPrompt("test-plan");
-		logger$11.debug({ storyKey }, "Retrieved test-plan prompt template from pack");
+		logger$13.debug({ storyKey }, "Retrieved test-plan prompt template from pack");
 	} catch (err) {
 		const error = err instanceof Error ? err.message : String(err);
-		logger$11.warn({
+		logger$13.warn({
 			storyKey,
 			error
 		}, "Failed to retrieve test-plan prompt template");
@@ -6283,14 +6288,14 @@ async function runTestPlan(deps, params) {
 		storyContent = await readFile$1(storyFilePath, "utf-8");
 	} catch (err) {
 		if (err.code === "ENOENT") {
-			logger$11.warn({
+			logger$13.warn({
 				storyKey,
 				storyFilePath
 			}, "Story file not found for test planning");
 			return makeTestPlanFailureResult("story_file_not_found");
 		}
 		const error = err instanceof Error ? err.message : String(err);
-		logger$11.warn({
+		logger$13.warn({
 			storyKey,
 			storyFilePath,
 			error
@@ -6307,7 +6312,7 @@ async function runTestPlan(deps, params) {
 		content: archConstraintsContent,
 		priority: "optional"
 	}], TOKEN_CEILING);
-	logger$11.info({
+	logger$13.info({
 		storyKey,
 		tokenCount,
 		ceiling: TOKEN_CEILING,
@@ -6321,12 +6326,13 @@ async function runTestPlan(deps, params) {
 			taskType: "test-plan",
 			timeout: DEFAULT_TIMEOUT_MS,
 			outputSchema: TestPlanResultSchema,
-			...deps.projectRoot !== void 0 ? { workingDirectory: deps.projectRoot } : {}
+			...deps.projectRoot !== void 0 ? { workingDirectory: deps.projectRoot } : {},
+			...deps.otlpEndpoint !== void 0 ? { otlpEndpoint: deps.otlpEndpoint } : {}
 		});
 		dispatchResult = await handle.result;
 	} catch (err) {
 		const error = err instanceof Error ? err.message : String(err);
-		logger$11.warn({
+		logger$13.warn({
 			storyKey,
 			error
 		}, "Test-plan dispatch threw an unexpected error");
@@ -6337,7 +6343,7 @@ async function runTestPlan(deps, params) {
 		output: dispatchResult.tokenEstimate.output
 	};
 	if (dispatchResult.status === "timeout") {
-		logger$11.warn({
+		logger$13.warn({
 			storyKey,
 			durationMs: dispatchResult.durationMs
 		}, "Test-plan dispatch timed out");
@@ -6347,7 +6353,7 @@ async function runTestPlan(deps, params) {
 		};
 	}
 	if (dispatchResult.status === "failed" || dispatchResult.exitCode !== 0) {
-		logger$11.warn({
+		logger$13.warn({
 			storyKey,
 			exitCode: dispatchResult.exitCode,
 			status: dispatchResult.status
@@ -6359,7 +6365,7 @@ async function runTestPlan(deps, params) {
 	}
 	if (dispatchResult.parseError !== null || dispatchResult.parsed === null) {
 		const details = dispatchResult.parseError ?? "parsed result was null";
-		logger$11.warn({
+		logger$13.warn({
 			storyKey,
 			parseError: details
 		}, "Test-plan YAML schema validation failed");
@@ -6382,19 +6388,19 @@ async function runTestPlan(deps, params) {
 			}),
 			rationale: `Test plan for ${storyKey}: ${parsed.test_files.length} test files, categories: ${parsed.test_categories.join(", ")}`
 		});
-		logger$11.info({
+		logger$13.info({
 			storyKey,
 			fileCount: parsed.test_files.length,
 			categories: parsed.test_categories
 		}, "Test plan stored in decision store");
 	} catch (err) {
 		const error = err instanceof Error ? err.message : String(err);
-		logger$11.warn({
+		logger$13.warn({
 			storyKey,
 			error
 		}, "Failed to store test plan in decision store — proceeding anyway");
 	}
-	logger$11.info({
+	logger$13.info({
 		storyKey,
 		result: parsed.result
 	}, "Test-plan workflow completed");
@@ -6434,14 +6440,14 @@ function getArchConstraints$1(deps) {
 		if (constraints.length === 0) return "";
 		return constraints.map((d) => `${d.key}: ${d.value}`).join("\n");
 	} catch (err) {
-		logger$11.warn({ error: err instanceof Error ? err.message : String(err) }, "Failed to retrieve architecture constraints for test-plan — proceeding without them");
+		logger$13.warn({ error: err instanceof Error ? err.message : String(err) }, "Failed to retrieve architecture constraints for test-plan — proceeding without them");
 		return "";
 	}
 }
 
 //#endregion
 //#region src/modules/compiled-workflows/test-expansion.ts
-const logger$10 = createLogger("compiled-workflows:test-expansion");
+const logger$12 = createLogger("compiled-workflows:test-expansion");
 function defaultFallbackResult(error, tokenUsage) {
 	return {
 		expansion_priority: "low",
@@ -6471,14 +6477,14 @@ function defaultFallbackResult(error, tokenUsage) {
 async function runTestExpansion(deps, params) {
 	const { storyKey, storyFilePath, pipelineRunId, filesModified, workingDirectory } = params;
 	const cwd = workingDirectory ?? process.cwd();
-	logger$10.debug({
+	logger$12.debug({
 		storyKey,
 		storyFilePath,
 		cwd,
 		pipelineRunId
 	}, "Starting test-expansion workflow");
 	const { ceiling: TOKEN_CEILING, source: tokenCeilingSource } = getTokenCeiling("test-expansion", deps.tokenCeilings);
-	logger$10.info({
+	logger$12.info({
 		workflow: "test-expansion",
 		ceiling: TOKEN_CEILING,
 		source: tokenCeilingSource
@@ -6488,7 +6494,7 @@ async function runTestExpansion(deps, params) {
 		template = await deps.pack.getPrompt("test-expansion");
 	} catch (err) {
 		const error = err instanceof Error ? err.message : String(err);
-		logger$10.warn({ error }, "Failed to retrieve test-expansion prompt template");
+		logger$12.warn({ error }, "Failed to retrieve test-expansion prompt template");
 		return defaultFallbackResult(`Failed to retrieve prompt template: ${error}`, {
 			input: 0,
 			output: 0
@@ -6499,7 +6505,7 @@ async function runTestExpansion(deps, params) {
 		storyContent = await readFile$1(storyFilePath, "utf-8");
 	} catch (err) {
 		const error = err instanceof Error ? err.message : String(err);
-		logger$10.warn({
+		logger$12.warn({
 			storyFilePath,
 			error
 		}, "Failed to read story file");
@@ -6519,12 +6525,12 @@ async function runTestExpansion(deps, params) {
 		const scopedTotal = nonDiffTokens + countTokens(scopedDiff);
 		if (scopedTotal <= TOKEN_CEILING) {
 			gitDiffContent = scopedDiff;
-			logger$10.debug({
+			logger$12.debug({
 				fileCount: filesModified.length,
 				tokenCount: scopedTotal
 			}, "Using scoped file diff");
 		} else {
-			logger$10.warn({
+			logger$12.warn({
 				estimatedTotal: scopedTotal,
 				ceiling: TOKEN_CEILING,
 				fileCount: filesModified.length
@@ -6532,7 +6538,7 @@ async function runTestExpansion(deps, params) {
 			gitDiffContent = await getGitDiffStatSummary(cwd);
 		}
 	} catch (err) {
-		logger$10.warn({ error: err instanceof Error ? err.message : String(err) }, "Failed to get git diff — proceeding with empty diff");
+		logger$12.warn({ error: err instanceof Error ? err.message : String(err) }, "Failed to get git diff — proceeding with empty diff");
 	}
 	const sections = [
 		{
@@ -6552,11 +6558,11 @@ async function runTestExpansion(deps, params) {
 		}
 	];
 	const assembleResult = assemblePrompt(template, sections, TOKEN_CEILING);
-	if (assembleResult.truncated) logger$10.warn({
+	if (assembleResult.truncated) logger$12.warn({
 		storyKey,
 		tokenCount: assembleResult.tokenCount
 	}, "Test-expansion prompt truncated to fit token ceiling");
-	logger$10.debug({
+	logger$12.debug({
 		storyKey,
 		tokenCount: assembleResult.tokenCount,
 		truncated: assembleResult.truncated
@@ -6567,14 +6573,15 @@ async function runTestExpansion(deps, params) {
 		agent: "claude-code",
 		taskType: "test-expansion",
 		outputSchema: TestExpansionResultSchema,
-		workingDirectory: deps.projectRoot
+		workingDirectory: deps.projectRoot,
+		...deps.otlpEndpoint !== void 0 ? { otlpEndpoint: deps.otlpEndpoint } : {}
 	});
 	let dispatchResult;
 	try {
 		dispatchResult = await handle.result;
 	} catch (err) {
 		const error = err instanceof Error ? err.message : String(err);
-		logger$10.warn({
+		logger$12.warn({
 			storyKey,
 			error
 		}, "Test-expansion dispatch threw unexpected error");
@@ -6589,19 +6596,19 @@ async function runTestExpansion(deps, params) {
 	};
 	if (dispatchResult.status === "failed") {
 		const errorMsg = `Dispatch status: failed. Exit code: ${dispatchResult.exitCode}. ${dispatchResult.parseError ?? ""}`.trim();
-		logger$10.warn({
+		logger$12.warn({
 			storyKey,
 			exitCode: dispatchResult.exitCode
 		}, "Test-expansion dispatch failed");
 		return defaultFallbackResult(errorMsg, tokenUsage);
 	}
 	if (dispatchResult.status === "timeout") {
-		logger$10.warn({ storyKey }, "Test-expansion dispatch timed out");
+		logger$12.warn({ storyKey }, "Test-expansion dispatch timed out");
 		return defaultFallbackResult("Dispatch status: timeout. The agent did not complete within the allowed time.", tokenUsage);
 	}
 	if (dispatchResult.parsed === null) {
 		const details = dispatchResult.parseError ?? "No YAML block found in output";
-		logger$10.warn({
+		logger$12.warn({
 			storyKey,
 			details
 		}, "Test-expansion output has no parseable YAML");
@@ -6610,14 +6617,14 @@ async function runTestExpansion(deps, params) {
 	const parseResult = TestExpansionResultSchema.safeParse(dispatchResult.parsed);
 	if (!parseResult.success) {
 		const details = parseResult.error.message;
-		logger$10.warn({
+		logger$12.warn({
 			storyKey,
 			details
 		}, "Test-expansion output failed schema validation");
 		return defaultFallbackResult(`schema_validation_failed: ${details}`, tokenUsage);
 	}
 	const parsed = parseResult.data;
-	logger$10.info({
+	logger$12.info({
 		storyKey,
 		expansion_priority: parsed.expansion_priority,
 		coverage_gaps: parsed.coverage_gaps.length,
@@ -6642,7 +6649,7 @@ function getArchConstraints(deps) {
 		if (constraints.length === 0) return "";
 		return constraints.map((d) => `${d.key}: ${d.value}`).join("\n");
 	} catch (err) {
-		logger$10.warn({ error: err instanceof Error ? err.message : String(err) }, "Failed to retrieve architecture constraints");
+		logger$12.warn({ error: err instanceof Error ? err.message : String(err) }, "Failed to retrieve architecture constraints");
 		return "";
 	}
 }
@@ -7766,7 +7773,8 @@ var DoltStateStore = class DoltStateStore {
 			const entries = [];
 			for (const row of rows) {
 				const hash = String(row.commit_hash ?? "");
-				const timestamp = row.date instanceof Date ? row.date.toISOString() : String(row.date ?? "");
+				const dateVal = row.date;
+				const timestamp = dateVal instanceof Date ? dateVal.toISOString() : String(dateVal ?? "");
 				const message = String(row.message ?? "");
 				const author = row.committer ? String(row.committer) : void 0;
 				const storyKeyMatch = /story\/([0-9]+-[0-9]+)/i.exec(message);
@@ -7929,7 +7937,7 @@ function createDoltClient(options) {
 
 //#endregion
 //#region src/modules/state/index.ts
-const logger$9 = createLogger("state:factory");
+const logger$11 = createLogger("state:factory");
 /**
 * Synchronously check whether Dolt is available and a Dolt repo exists at the
 * canonical state path under `basePath`.
@@ -7976,14 +7984,14 @@ function createStateStore(config = {}) {
 		const repoPath = config.basePath ?? process.cwd();
 		const detection = detectDoltAvailableSync(repoPath);
 		if (detection.available) {
-			logger$9.debug(`Dolt detected, using DoltStateStore (state path: ${join$1(repoPath, ".substrate", "state")})`);
+			logger$11.debug(`Dolt detected, using DoltStateStore (state path: ${join$1(repoPath, ".substrate", "state")})`);
 			const client = new DoltClient({ repoPath });
 			return new DoltStateStore({
 				repoPath,
 				client
 			});
 		} else {
-			logger$9.debug(`Dolt not found, using FileStateStore (reason: ${detection.reason})`);
+			logger$11.debug(`Dolt not found, using FileStateStore (reason: ${detection.reason})`);
 			return new FileStateStore({ basePath: config.basePath });
 		}
 	}
@@ -7992,7 +8000,7 @@ function createStateStore(config = {}) {
 
 //#endregion
 //#region src/cli/commands/health.ts
-const logger$8 = createLogger("health-cmd");
+const logger$10 = createLogger("health-cmd");
 /** Default stall threshold in seconds — also used by supervisor default */
 const DEFAULT_STALL_THRESHOLD_SECONDS = 600;
 /**
@@ -8294,7 +8302,7 @@ async function runHealthAction(options) {
 		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$8.error({ err }, "health action failed");
+		logger$10.error({ err }, "health action failed");
 		return 1;
 	}
 }
@@ -8341,7 +8349,7 @@ function registerHealthCommand(program, _version = "0.0.0", projectRoot = proces
 
 //#endregion
 //#region src/modules/implementation-orchestrator/seed-methodology-context.ts
-const logger$7 = createLogger("implementation-orchestrator:seed");
+const logger$9 = createLogger("implementation-orchestrator:seed");
 /** Max chars for the architecture summary seeded into decisions */
 const MAX_ARCH_CHARS = 6e3;
 /** Max chars per epic shard (fallback when per-story extraction returns null) */
@@ -8375,12 +8383,12 @@ function seedMethodologyContext(db, projectRoot) {
 		const testCount = seedTestPatterns(db, projectRoot);
 		if (testCount === -1) result.skippedCategories.push("test-patterns");
 		else result.decisionsCreated += testCount;
-		logger$7.info({
+		logger$9.info({
 			decisionsCreated: result.decisionsCreated,
 			skippedCategories: result.skippedCategories
 		}, "Methodology context seeding complete");
 	} catch (err) {
-		logger$7.warn({ error: err instanceof Error ? err.message : String(err) }, "Methodology context seeding failed (non-fatal)");
+		logger$9.warn({ error: err instanceof Error ? err.message : String(err) }, "Methodology context seeding failed (non-fatal)");
 	}
 	return result;
 }
@@ -8424,7 +8432,7 @@ function seedArchitecture(db, projectRoot) {
 		});
 		count = 1;
 	}
-	logger$7.debug({ count }, "Seeded architecture decisions");
+	logger$9.debug({ count }, "Seeded architecture decisions");
 	return count;
 }
 /**
@@ -8448,11 +8456,11 @@ function seedEpicShards(db, projectRoot) {
 	const storedHashDecision = implementationDecisions.find((d) => d.category === "epic-shard-hash" && d.key === "epics-file");
 	const storedHash = storedHashDecision?.value;
 	if (storedHash === currentHash) {
-		logger$7.debug({ hash: currentHash }, "Epic shards up-to-date (hash unchanged) — skipping re-seed");
+		logger$9.debug({ hash: currentHash }, "Epic shards up-to-date (hash unchanged) — skipping re-seed");
 		return -1;
 	}
 	if (implementationDecisions.some((d) => d.category === "epic-shard")) {
-		logger$7.debug({
+		logger$9.debug({
 			storedHash,
 			currentHash
 		}, "Epics file changed — deleting stale epic-shard decisions");
@@ -8480,7 +8488,7 @@ function seedEpicShards(db, projectRoot) {
 		value: currentHash,
 		rationale: "SHA-256 hash of epics file content for change detection"
 	});
-	logger$7.debug({
+	logger$9.debug({
 		count,
 		hash: currentHash
 	}, "Seeded epic shard decisions");
@@ -8504,7 +8512,7 @@ function seedTestPatterns(db, projectRoot) {
 		value: patterns.slice(0, MAX_TEST_PATTERNS_CHARS),
 		rationale: "Detected from project configuration at orchestrator startup"
 	});
-	logger$7.debug("Seeded test patterns decision");
+	logger$9.debug("Seeded test patterns decision");
 	return 1;
 }
 /**
@@ -8677,7 +8685,7 @@ function findArtifact(projectRoot, candidates) {
 
 //#endregion
 //#region src/modules/agent-dispatch/interface-change-detector.ts
-const logger$6 = createLogger("interface-change-detector");
+const logger$8 = createLogger("interface-change-detector");
 /**
 * Extract exported interface and type names from TypeScript source content.
 *
@@ -8724,7 +8732,7 @@ function detectInterfaceChanges(options) {
 				for (const name of names) allNames.add(name);
 				sourceDirs.push(dirname$1(relPath));
 			} catch {
-				logger$6.debug({
+				logger$8.debug({
 					absPath,
 					storyKey
 				}, "Could not read modified file for interface extraction");
@@ -8765,7 +8773,7 @@ function detectInterfaceChanges(options) {
 			potentiallyAffectedTests: Array.from(affectedTests)
 		};
 	} catch (err) {
-		logger$6.warn({
+		logger$8.warn({
 			err,
 			storyKey: options.storyKey
 		}, "Interface change detection failed — skipping");
@@ -8933,6 +8941,1159 @@ function verifyContracts(declarations, projectRoot) {
 	return mismatches;
 }
 
+//#endregion
+//#region src/modules/telemetry/types.ts
+const ChildSpanSummarySchema = z.object({
+	spanId: z.string(),
+	name: z.string(),
+	toolName: z.string().optional(),
+	inputTokens: z.number(),
+	outputTokens: z.number(),
+	durationMs: z.number()
+});
+const TurnAnalysisSchema = z.object({
+	spanId: z.string(),
+	turnNumber: z.number().int().positive(),
+	name: z.string(),
+	timestamp: z.number(),
+	source: z.string(),
+	model: z.string().optional(),
+	inputTokens: z.number(),
+	outputTokens: z.number(),
+	cacheReadTokens: z.number(),
+	freshTokens: z.number(),
+	cacheHitRate: z.number(),
+	costUsd: z.number(),
+	durationMs: z.number(),
+	contextSize: z.number(),
+	contextDelta: z.number(),
+	toolName: z.string().optional(),
+	isContextSpike: z.boolean(),
+	childSpans: z.array(ChildSpanSummarySchema)
+});
+const SemanticCategorySchema = z.enum([
+	"tool_outputs",
+	"file_reads",
+	"system_prompts",
+	"conversation_history",
+	"user_prompts",
+	"other"
+]);
+const TrendSchema = z.enum([
+	"growing",
+	"stable",
+	"shrinking"
+]);
+const TopInvocationSchema = z.object({
+	spanId: z.string(),
+	name: z.string(),
+	toolName: z.string().optional(),
+	totalTokens: z.number(),
+	inputTokens: z.number(),
+	outputTokens: z.number()
+});
+const CategoryStatsSchema = z.object({
+	category: SemanticCategorySchema,
+	totalTokens: z.number(),
+	percentage: z.number(),
+	eventCount: z.number(),
+	avgTokensPerEvent: z.number(),
+	trend: TrendSchema
+});
+const ConsumerStatsSchema = z.object({
+	consumerKey: z.string(),
+	category: SemanticCategorySchema,
+	totalTokens: z.number(),
+	percentage: z.number(),
+	eventCount: z.number(),
+	topInvocations: z.array(TopInvocationSchema).max(20)
+});
+const ModelEfficiencySchema = z.object({
+	model: z.string(),
+	cacheHitRate: z.number(),
+	avgIoRatio: z.number(),
+	costPer1KOutputTokens: z.number()
+});
+const SourceEfficiencySchema = z.object({
+	source: z.string(),
+	compositeScore: z.number(),
+	turnCount: z.number()
+});
+const EfficiencyScoreSchema = z.object({
+	storyKey: z.string(),
+	timestamp: z.number(),
+	compositeScore: z.number().int().min(0).max(100),
+	cacheHitSubScore: z.number().min(0).max(100),
+	ioRatioSubScore: z.number().min(0).max(100),
+	contextManagementSubScore: z.number().min(0).max(100),
+	avgCacheHitRate: z.number(),
+	avgIoRatio: z.number(),
+	contextSpikeCount: z.number().int().nonnegative(),
+	totalTurns: z.number().int().nonnegative(),
+	perModelBreakdown: z.array(ModelEfficiencySchema),
+	perSourceBreakdown: z.array(SourceEfficiencySchema)
+});
+const RuleIdSchema = z.enum([
+	"biggest_consumers",
+	"large_file_reads",
+	"expensive_bash",
+	"repeated_tool_calls",
+	"context_growth_spike",
+	"growing_categories",
+	"cache_efficiency",
+	"per_model_comparison"
+]);
+const RecommendationSeveritySchema = z.enum([
+	"critical",
+	"warning",
+	"info"
+]);
+const RecommendationSchema = z.object({
+	id: z.string().length(16),
+	storyKey: z.string(),
+	sprintId: z.string().optional(),
+	ruleId: RuleIdSchema,
+	severity: RecommendationSeveritySchema,
+	title: z.string(),
+	description: z.string(),
+	potentialSavingsTokens: z.number().optional(),
+	potentialSavingsUsd: z.number().optional(),
+	actionTarget: z.string().optional(),
+	generatedAt: z.string()
+});
+
+//#endregion
+//#region src/modules/telemetry/persistence.ts
+const logger$7 = createLogger("telemetry:persistence");
+/**
+* Concrete SQLite-backed telemetry persistence.
+*
+* All prepared statements are compiled once at construction time.
+* Call `initSchema()` before using if the tables may not exist yet.
+*/
+var TelemetryPersistence = class {
+	_db;
+	_insertTurnAnalysis;
+	_getTurnAnalysis;
+	_insertEfficiencyScore;
+	_getEfficiencyScore;
+	_getEfficiencyScores;
+	_insertRecommendation;
+	_getRecommendations;
+	_getAllRecommendations;
+	_insertCategoryStats;
+	_getCategoryStats;
+	_getAllCategoryStats;
+	_insertConsumerStats;
+	_getConsumerStats;
+	constructor(db) {
+		this._db = db;
+		this._insertTurnAnalysis = this._db.prepare(`
+      INSERT OR REPLACE INTO turn_analysis (
+        story_key, span_id, turn_number, name, timestamp, source, model,
+        input_tokens, output_tokens, cache_read_tokens, fresh_tokens,
+        cache_hit_rate, cost_usd, duration_ms, context_size, context_delta,
+        tool_name, is_context_spike, child_spans_json
+      ) VALUES (
+        ?, ?, ?, ?, ?, ?, ?,
+        ?, ?, ?, ?,
+        ?, ?, ?, ?, ?,
+        ?, ?, ?
+      )
+    `);
+		this._getTurnAnalysis = this._db.prepare(`
+      SELECT * FROM turn_analysis
+      WHERE story_key = ?
+      ORDER BY turn_number ASC
+    `);
+		this._insertEfficiencyScore = this._db.prepare(`
+      INSERT OR REPLACE INTO efficiency_scores (
+        story_key, timestamp, composite_score,
+        cache_hit_sub_score, io_ratio_sub_score, context_management_sub_score,
+        avg_cache_hit_rate, avg_io_ratio, context_spike_count, total_turns,
+        per_model_json, per_source_json
+      ) VALUES (
+        ?, ?, ?,
+        ?, ?, ?,
+        ?, ?, ?, ?,
+        ?, ?
+      )
+    `);
+		this._getEfficiencyScore = this._db.prepare(`
+      SELECT * FROM efficiency_scores
+      WHERE story_key = ?
+      ORDER BY timestamp DESC
+      LIMIT 1
+    `);
+		this._getEfficiencyScores = this._db.prepare(`
+      SELECT * FROM efficiency_scores
+      ORDER BY timestamp DESC
+      LIMIT ?
+    `);
+		this._insertRecommendation = this._db.prepare(`
+      INSERT OR REPLACE INTO recommendations (
+        id, story_key, sprint_id, rule_id, severity, title, description,
+        potential_savings_tokens, potential_savings_usd, action_target, generated_at
+      ) VALUES (
+        ?, ?, ?, ?, ?, ?, ?,
+        ?, ?, ?, ?
+      )
+    `);
+		this._getRecommendations = this._db.prepare(`
+      SELECT * FROM recommendations
+      WHERE story_key = ?
+      ORDER BY
+        CASE severity
+          WHEN 'critical' THEN 1
+          WHEN 'warning' THEN 2
+          ELSE 3
+        END,
+        COALESCE(potential_savings_tokens, 0) DESC
+    `);
+		this._getAllRecommendations = this._db.prepare(`
+      SELECT * FROM recommendations
+      ORDER BY
+        CASE severity
+          WHEN 'critical' THEN 1
+          WHEN 'warning' THEN 2
+          ELSE 3
+        END,
+        COALESCE(potential_savings_tokens, 0) DESC
+      LIMIT ?
+    `);
+		this._insertCategoryStats = this._db.prepare(`
+      INSERT OR IGNORE INTO category_stats (
+        story_key, category, total_tokens, percentage, event_count,
+        avg_tokens_per_event, trend
+      ) VALUES (?, ?, ?, ?, ?, ?, ?)
+    `);
+		this._getCategoryStats = this._db.prepare(`
+      SELECT * FROM category_stats
+      WHERE story_key = ?
+      ORDER BY total_tokens DESC
+    `);
+		this._getAllCategoryStats = this._db.prepare(`
+      SELECT category, SUM(total_tokens) AS total_tokens,
+             AVG(percentage) AS percentage,
+             SUM(event_count) AS event_count,
+             AVG(avg_tokens_per_event) AS avg_tokens_per_event,
+             MAX(trend) AS trend
+      FROM category_stats
+      GROUP BY category
+      ORDER BY total_tokens DESC
+    `);
+		this._insertConsumerStats = this._db.prepare(`
+      INSERT OR IGNORE INTO consumer_stats (
+        story_key, consumer_key, category, total_tokens, percentage,
+        event_count, top_invocations_json
+      ) VALUES (?, ?, ?, ?, ?, ?, ?)
+    `);
+		this._getConsumerStats = this._db.prepare(`
+      SELECT * FROM consumer_stats
+      WHERE story_key = ?
+      ORDER BY total_tokens DESC
+    `);
+	}
+	/**
+	* Apply the telemetry schema DDL to the database.
+	* Idempotent — uses CREATE TABLE IF NOT EXISTS.
+	*/
+	initSchema() {
+		this._db.exec(`
+      CREATE TABLE IF NOT EXISTS turn_analysis (
+        story_key         VARCHAR(64)    NOT NULL,
+        span_id           VARCHAR(128)   NOT NULL,
+        turn_number       INTEGER        NOT NULL,
+        name              VARCHAR(255)   NOT NULL DEFAULT '',
+        timestamp         BIGINT         NOT NULL DEFAULT 0,
+        source            VARCHAR(32)    NOT NULL DEFAULT '',
+        model             VARCHAR(64),
+        input_tokens      INTEGER        NOT NULL DEFAULT 0,
+        output_tokens     INTEGER        NOT NULL DEFAULT 0,
+        cache_read_tokens INTEGER        NOT NULL DEFAULT 0,
+        fresh_tokens      INTEGER        NOT NULL DEFAULT 0,
+        cache_hit_rate    DOUBLE         NOT NULL DEFAULT 0,
+        cost_usd          DOUBLE         NOT NULL DEFAULT 0,
+        duration_ms       INTEGER        NOT NULL DEFAULT 0,
+        context_size      INTEGER        NOT NULL DEFAULT 0,
+        context_delta     INTEGER        NOT NULL DEFAULT 0,
+        tool_name         VARCHAR(128),
+        is_context_spike  BOOLEAN        NOT NULL DEFAULT 0,
+        child_spans_json  TEXT           NOT NULL DEFAULT '[]',
+        PRIMARY KEY (story_key, span_id)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_turn_analysis_story
+        ON turn_analysis (story_key, turn_number);
+
+      CREATE TABLE IF NOT EXISTS efficiency_scores (
+        story_key                     VARCHAR(64)  NOT NULL,
+        timestamp                     BIGINT       NOT NULL,
+        composite_score               INTEGER      NOT NULL DEFAULT 0,
+        cache_hit_sub_score           DOUBLE       NOT NULL DEFAULT 0,
+        io_ratio_sub_score            DOUBLE       NOT NULL DEFAULT 0,
+        context_management_sub_score  DOUBLE       NOT NULL DEFAULT 0,
+        avg_cache_hit_rate            DOUBLE       NOT NULL DEFAULT 0,
+        avg_io_ratio                  DOUBLE       NOT NULL DEFAULT 0,
+        context_spike_count           INTEGER      NOT NULL DEFAULT 0,
+        total_turns                   INTEGER      NOT NULL DEFAULT 0,
+        per_model_json                TEXT         NOT NULL DEFAULT '[]',
+        per_source_json               TEXT         NOT NULL DEFAULT '[]',
+        PRIMARY KEY (story_key, timestamp)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_efficiency_story
+        ON efficiency_scores (story_key, timestamp DESC);
+
+      CREATE TABLE IF NOT EXISTS recommendations (
+        id                       VARCHAR(16)   NOT NULL,
+        story_key                VARCHAR(64)   NOT NULL,
+        sprint_id                VARCHAR(64),
+        rule_id                  VARCHAR(64)   NOT NULL,
+        severity                 VARCHAR(16)   NOT NULL,
+        title                    TEXT          NOT NULL,
+        description              TEXT          NOT NULL,
+        potential_savings_tokens INTEGER,
+        potential_savings_usd    DOUBLE,
+        action_target            TEXT,
+        generated_at             VARCHAR(32)   NOT NULL,
+        PRIMARY KEY (id)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_recommendations_story
+        ON recommendations (story_key, severity);
+
+      CREATE TABLE IF NOT EXISTS category_stats (
+        story_key            VARCHAR(100)   NOT NULL,
+        category             VARCHAR(30)    NOT NULL,
+        total_tokens         BIGINT         NOT NULL DEFAULT 0,
+        percentage           DECIMAL(6,3)   NOT NULL DEFAULT 0,
+        event_count          INTEGER        NOT NULL DEFAULT 0,
+        avg_tokens_per_event DECIMAL(12,2)  NOT NULL DEFAULT 0,
+        trend                VARCHAR(10)    NOT NULL DEFAULT 'stable',
+        PRIMARY KEY (story_key, category)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_category_stats_story
+        ON category_stats (story_key, total_tokens);
+
+      CREATE TABLE IF NOT EXISTS consumer_stats (
+        story_key            VARCHAR(100)   NOT NULL,
+        consumer_key         VARCHAR(300)   NOT NULL,
+        category             VARCHAR(30)    NOT NULL,
+        total_tokens         BIGINT         NOT NULL DEFAULT 0,
+        percentage           DECIMAL(6,3)   NOT NULL DEFAULT 0,
+        event_count          INTEGER        NOT NULL DEFAULT 0,
+        top_invocations_json TEXT,
+        PRIMARY KEY (story_key, consumer_key)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_consumer_stats_story
+        ON consumer_stats (story_key, total_tokens);
+    `);
+	}
+	async storeTurnAnalysis(storyKey, turns) {
+		if (turns.length === 0) return;
+		const insertAll = this._db.transaction((rows) => {
+			for (const turn of rows) this._insertTurnAnalysis.run(storyKey, turn.spanId, turn.turnNumber, turn.name, turn.timestamp, turn.source, turn.model ?? null, turn.inputTokens, turn.outputTokens, turn.cacheReadTokens, turn.freshTokens, turn.cacheHitRate, turn.costUsd, turn.durationMs, turn.contextSize, turn.contextDelta, turn.toolName ?? null, turn.isContextSpike ? 1 : 0, JSON.stringify(turn.childSpans));
+		});
+		insertAll(turns);
+		logger$7.debug({
+			storyKey,
+			count: turns.length
+		}, "Stored turn analysis");
+	}
+	async getTurnAnalysis(storyKey) {
+		const rows = this._getTurnAnalysis.all(storyKey);
+		if (rows.length === 0) return [];
+		return rows.map((row) => {
+			const raw = {
+				spanId: row.span_id,
+				turnNumber: row.turn_number,
+				name: row.name,
+				timestamp: row.timestamp,
+				source: row.source,
+				model: row.model ?? void 0,
+				inputTokens: row.input_tokens,
+				outputTokens: row.output_tokens,
+				cacheReadTokens: row.cache_read_tokens,
+				freshTokens: row.fresh_tokens,
+				cacheHitRate: row.cache_hit_rate,
+				costUsd: row.cost_usd,
+				durationMs: row.duration_ms,
+				contextSize: row.context_size,
+				contextDelta: row.context_delta,
+				toolName: row.tool_name ?? void 0,
+				isContextSpike: row.is_context_spike === 1,
+				childSpans: JSON.parse(row.child_spans_json)
+			};
+			return TurnAnalysisSchema.parse(raw);
+		});
+	}
+	async storeEfficiencyScore(score) {
+		this._insertEfficiencyScore.run(score.storyKey, score.timestamp, score.compositeScore, score.cacheHitSubScore, score.ioRatioSubScore, score.contextManagementSubScore, score.avgCacheHitRate, score.avgIoRatio, score.contextSpikeCount, score.totalTurns, JSON.stringify(score.perModelBreakdown), JSON.stringify(score.perSourceBreakdown));
+		logger$7.debug({
+			storyKey: score.storyKey,
+			compositeScore: score.compositeScore
+		}, "Stored efficiency score");
+	}
+	async getEfficiencyScore(storyKey) {
+		const row = this._getEfficiencyScore.get(storyKey);
+		if (row === void 0) return null;
+		const raw = {
+			storyKey: row.story_key,
+			timestamp: row.timestamp,
+			compositeScore: row.composite_score,
+			cacheHitSubScore: row.cache_hit_sub_score,
+			ioRatioSubScore: row.io_ratio_sub_score,
+			contextManagementSubScore: row.context_management_sub_score,
+			avgCacheHitRate: row.avg_cache_hit_rate,
+			avgIoRatio: row.avg_io_ratio,
+			contextSpikeCount: row.context_spike_count,
+			totalTurns: row.total_turns,
+			perModelBreakdown: JSON.parse(row.per_model_json),
+			perSourceBreakdown: JSON.parse(row.per_source_json)
+		};
+		return EfficiencyScoreSchema.parse(raw);
+	}
+	/**
+	* Retrieve multiple efficiency scores ordered by timestamp DESC.
+	* Returns up to `limit` records (default 20).
+	*/
+	async getEfficiencyScores(limit = 20) {
+		const rows = this._getEfficiencyScores.all(limit);
+		if (rows.length === 0) return [];
+		return rows.map((row) => {
+			const raw = {
+				storyKey: row.story_key,
+				timestamp: row.timestamp,
+				compositeScore: row.composite_score,
+				cacheHitSubScore: row.cache_hit_sub_score,
+				ioRatioSubScore: row.io_ratio_sub_score,
+				contextManagementSubScore: row.context_management_sub_score,
+				avgCacheHitRate: row.avg_cache_hit_rate,
+				avgIoRatio: row.avg_io_ratio,
+				contextSpikeCount: row.context_spike_count,
+				totalTurns: row.total_turns,
+				perModelBreakdown: JSON.parse(row.per_model_json),
+				perSourceBreakdown: JSON.parse(row.per_source_json)
+			};
+			return EfficiencyScoreSchema.parse(raw);
+		});
+	}
+	/**
+	* Batch-insert all recommendations for a story in a single transaction.
+	* Uses INSERT OR REPLACE for idempotency (IDs are deterministic hashes).
+	*/
+	async saveRecommendations(storyKey, recs) {
+		if (recs.length === 0) return;
+		const insertAll = this._db.transaction((rows) => {
+			for (const rec of rows) this._insertRecommendation.run(rec.id, rec.storyKey, rec.sprintId ?? null, rec.ruleId, rec.severity, rec.title, rec.description, rec.potentialSavingsTokens ?? null, rec.potentialSavingsUsd ?? null, rec.actionTarget ?? null, rec.generatedAt);
+		});
+		insertAll(recs);
+		logger$7.debug({
+			storyKey,
+			count: recs.length
+		}, "Saved recommendations");
+	}
+	/**
+	* Retrieve recommendations for a story ordered by severity (critical first)
+	* then by potentialSavingsTokens descending.
+	* Each row is validated with RecommendationSchema.parse().
+	*/
+	async getRecommendations(storyKey) {
+		const rows = this._getRecommendations.all(storyKey);
+		if (rows.length === 0) return [];
+		return rows.map((row) => {
+			const raw = {
+				id: row.id,
+				storyKey: row.story_key,
+				sprintId: row.sprint_id ?? void 0,
+				ruleId: row.rule_id,
+				severity: row.severity,
+				title: row.title,
+				description: row.description,
+				potentialSavingsTokens: row.potential_savings_tokens != null ? Number(row.potential_savings_tokens) : void 0,
+				potentialSavingsUsd: row.potential_savings_usd != null ? Number(row.potential_savings_usd) : void 0,
+				actionTarget: row.action_target ?? void 0,
+				generatedAt: row.generated_at
+			};
+			return RecommendationSchema.parse(raw);
+		});
+	}
+	/**
+	* Retrieve all recommendations across all stories, ordered by severity (critical first)
+	* then by potentialSavingsTokens descending. Returns up to `limit` records (default 20).
+	*/
+	async getAllRecommendations(limit = 20) {
+		const rows = this._getAllRecommendations.all(limit);
+		if (rows.length === 0) return [];
+		return rows.map((row) => {
+			const raw = {
+				id: row.id,
+				storyKey: row.story_key,
+				sprintId: row.sprint_id ?? void 0,
+				ruleId: row.rule_id,
+				severity: row.severity,
+				title: row.title,
+				description: row.description,
+				potentialSavingsTokens: row.potential_savings_tokens != null ? Number(row.potential_savings_tokens) : void 0,
+				potentialSavingsUsd: row.potential_savings_usd != null ? Number(row.potential_savings_usd) : void 0,
+				actionTarget: row.action_target ?? void 0,
+				generatedAt: row.generated_at
+			};
+			return RecommendationSchema.parse(raw);
+		});
+	}
+	/**
+	* Batch-insert category stats for a story.
+	* Uses INSERT OR IGNORE — existing rows for the same (story_key, category) are preserved.
+	*/
+	async storeCategoryStats(storyKey, stats) {
+		if (stats.length === 0) return;
+		const insertAll = this._db.transaction((rows) => {
+			for (const stat$2 of rows) this._insertCategoryStats.run(storyKey, stat$2.category, stat$2.totalTokens, stat$2.percentage, stat$2.eventCount, stat$2.avgTokensPerEvent, stat$2.trend);
+		});
+		insertAll(stats);
+		logger$7.debug({
+			storyKey,
+			count: stats.length
+		}, "Stored category stats");
+	}
+	/**
+	* Retrieve category stats for a story ordered by total_tokens descending.
+	* Each row is validated with CategoryStatsSchema.parse().
+	* Returns [] when no rows exist for the given storyKey.
+	*/
+	async getCategoryStats(storyKey) {
+		const rows = storyKey === "" ? this._getAllCategoryStats.all() : this._getCategoryStats.all(storyKey);
+		if (rows.length === 0) return [];
+		return rows.map((row) => {
+			const raw = {
+				category: row.category,
+				totalTokens: Number(row.total_tokens),
+				percentage: Number(row.percentage),
+				eventCount: Number(row.event_count),
+				avgTokensPerEvent: Number(row.avg_tokens_per_event),
+				trend: row.trend
+			};
+			return CategoryStatsSchema.parse(raw);
+		});
+	}
+	/**
+	* Batch-insert consumer stats for a story.
+	* topInvocations is serialized to JSON.
+	* Uses INSERT OR IGNORE — existing rows for the same (story_key, consumer_key) are preserved.
+	*/
+	async storeConsumerStats(storyKey, consumers) {
+		if (consumers.length === 0) return;
+		const insertAll = this._db.transaction((rows) => {
+			for (const consumer of rows) this._insertConsumerStats.run(storyKey, consumer.consumerKey, consumer.category, consumer.totalTokens, consumer.percentage, consumer.eventCount, JSON.stringify(consumer.topInvocations));
+		});
+		insertAll(consumers);
+		logger$7.debug({
+			storyKey,
+			count: consumers.length
+		}, "Stored consumer stats");
+	}
+	/**
+	* Retrieve consumer stats for a story ordered by total_tokens descending.
+	* Deserializes top_invocations_json back to TopInvocation[].
+	* Each row is validated with ConsumerStatsSchema.parse().
+	* Returns [] when no rows exist for the given storyKey.
+	*/
+	async getConsumerStats(storyKey) {
+		const rows = this._getConsumerStats.all(storyKey);
+		if (rows.length === 0) return [];
+		return rows.map((row) => {
+			const raw = {
+				consumerKey: row.consumer_key,
+				category: row.category,
+				totalTokens: Number(row.total_tokens),
+				percentage: Number(row.percentage),
+				eventCount: Number(row.event_count),
+				topInvocations: JSON.parse(row.top_invocations_json ?? "[]")
+			};
+			return ConsumerStatsSchema.parse(raw);
+		});
+	}
+};
+
+//#endregion
+//#region src/errors/app-error.ts
+/**
+* AppError — base error class for substrate with machine-readable error codes.
+*
+* Architecture decision: AppError base class with numeric exit codes
+* (process.exit codes: 0 success, 1 user error, 2 internal error).
+* All structured errors in substrate should extend this class.
+*/
+/**
+* Base error class for substrate with machine-readable error codes and exit codes.
+*
+* @example
+*   throw new AppError('ERR_TELEMETRY_NOT_STARTED', 2, 'IngestionServer is not started')
+*/
+var AppError = class extends Error {
+	/** Machine-readable error code (e.g. ERR_DB_LOCKED, ERR_INVALID_INPUT) */
+	code;
+	/** Process exit code: 0 success, 1 user error, 2 internal error */
+	exitCode;
+	constructor(code, exitCode, message) {
+		super(message);
+		this.name = "AppError";
+		this.code = code;
+		this.exitCode = exitCode;
+	}
+};
+
+//#endregion
+//#region src/modules/telemetry/ingestion-server.ts
+const logger$6 = createLogger("telemetry:ingestion-server");
+/**
+* Error thrown by IngestionServer for server lifecycle violations.
+* Extends AppError to align with the project-standard error-handling pattern
+* (AppError base class with numeric exit codes).
+*/
+var TelemetryError = class extends AppError {
+	constructor(code, message) {
+		super(code, 2, message);
+		this.name = "TelemetryError";
+	}
+};
+/**
+* Local HTTP server that accepts OTLP payloads from Claude Code sub-agents.
+*
+* Binds to `port` (default 4318). Use port 0 in tests for an OS-assigned port.
+*/
+var IngestionServer = class {
+	_server = null;
+	_port;
+	constructor(options = {}) {
+		this._port = options.port ?? 4318;
+	}
+	/**
+	* Start the HTTP ingestion server.
+	* Resolves when the server is listening and ready to accept connections.
+	*/
+	async start() {
+		if (this._server !== null) {
+			logger$6.warn("IngestionServer.start() called while already started — ignoring");
+			return;
+		}
+		return new Promise((resolve$2, reject) => {
+			const server = createServer(this._handleRequest.bind(this));
+			server.on("error", (err) => {
+				logger$6.error({ err }, "IngestionServer failed to start");
+				reject(err);
+			});
+			server.listen(this._port, "127.0.0.1", () => {
+				this._server = server;
+				const addr = server.address();
+				logger$6.info({ port: addr.port }, "IngestionServer listening");
+				resolve$2();
+			});
+		});
+	}
+	/**
+	* Stop the HTTP ingestion server.
+	* Resolves when the server has closed all connections.
+	*/
+	async stop() {
+		const server = this._server;
+		if (server === null) return;
+		this._server = null;
+		return new Promise((resolve$2, reject) => {
+			server.close((err) => {
+				if (err !== void 0 && err !== null) reject(err);
+				else {
+					logger$6.info("IngestionServer stopped");
+					resolve$2();
+				}
+			});
+		});
+	}
+	/**
+	* Return the 5 OTLP environment variables to inject into sub-agent processes.
+	*
+	* @throws {TelemetryError} ERR_TELEMETRY_NOT_STARTED if the server is not started.
+	*/
+	getOtlpEnvVars() {
+		const addr = this._server?.address();
+		if (addr === null || addr === void 0 || typeof addr === "string") throw new TelemetryError("ERR_TELEMETRY_NOT_STARTED", "IngestionServer is not started — call start() before getOtlpEnvVars()");
+		const endpoint = `http://localhost:${addr.port}`;
+		return {
+			CLAUDE_CODE_ENABLE_TELEMETRY: "1",
+			OTEL_LOGS_EXPORTER: "otlp",
+			OTEL_METRICS_EXPORTER: "otlp",
+			OTEL_EXPORTER_OTLP_PROTOCOL: "http/json",
+			OTEL_EXPORTER_OTLP_ENDPOINT: endpoint
+		};
+	}
+	_handleRequest(_req, res) {
+		const chunks = [];
+		_req.on("data", (chunk) => {
+			chunks.push(chunk);
+		});
+		_req.on("end", () => {
+			const body = Buffer.concat(chunks).toString("utf-8");
+			logger$6.trace({
+				url: _req.url,
+				bodyLength: body.length
+			}, "OTLP payload received");
+			res.writeHead(200, { "Content-Type": "application/json" });
+			res.end("{}");
+		});
+		_req.on("error", (err) => {
+			logger$6.warn({ err }, "Error reading OTLP request body");
+			res.writeHead(400);
+			res.end("Bad Request");
+		});
+	}
+};
+
+//#endregion
+//#region src/modules/telemetry/efficiency-scorer.ts
+var EfficiencyScorer = class {
+	_logger;
+	constructor(logger$26) {
+		this._logger = logger$26;
+	}
+	/**
+	* Compute an efficiency score for a story given its turn analyses.
+	*
+	* Returns a zeroed `EfficiencyScore` immediately when `turns` is empty.
+	*
+	* @param storyKey - The story identifier (e.g. "27-6")
+	* @param turns    - Turn analysis records from `TurnAnalyzer.analyze()`
+	*/
+	score(storyKey, turns) {
+		if (turns.length === 0) return {
+			storyKey,
+			timestamp: Date.now(),
+			compositeScore: 0,
+			cacheHitSubScore: 0,
+			ioRatioSubScore: 0,
+			contextManagementSubScore: 0,
+			avgCacheHitRate: 0,
+			avgIoRatio: 0,
+			contextSpikeCount: 0,
+			totalTurns: 0,
+			perModelBreakdown: [],
+			perSourceBreakdown: []
+		};
+		const avgCacheHitRate = this._computeAvgCacheHitRate(turns);
+		const avgIoRatio = this._computeAvgIoRatio(turns);
+		const contextSpikeCount = turns.filter((t) => t.isContextSpike).length;
+		const totalTurns = turns.length;
+		const cacheHitSubScore = this._computeCacheHitSubScore(turns);
+		const ioRatioSubScore = this._computeIoRatioSubScore(turns);
+		const contextManagementSubScore = this._computeContextManagementSubScore(turns);
+		const compositeScore = Math.round(cacheHitSubScore * .4 + ioRatioSubScore * .3 + contextManagementSubScore * .3);
+		const perModelBreakdown = this._buildPerModelBreakdown(turns);
+		const perSourceBreakdown = this._buildPerSourceBreakdown(turns);
+		this._logger.info({
+			storyKey,
+			compositeScore,
+			contextSpikeCount
+		}, "Computed efficiency score");
+		return {
+			storyKey,
+			timestamp: Date.now(),
+			compositeScore,
+			cacheHitSubScore,
+			ioRatioSubScore,
+			contextManagementSubScore,
+			avgCacheHitRate,
+			avgIoRatio,
+			contextSpikeCount,
+			totalTurns,
+			perModelBreakdown,
+			perSourceBreakdown
+		};
+	}
+	/**
+	* Average cache hit rate across all turns, clamped to [0, 100].
+	* Formula: clamp(avgCacheHitRate × 100, 0, 100)
+	*/
+	_computeCacheHitSubScore(turns) {
+		const avg = this._computeAvgCacheHitRate(turns);
+		return this._clamp(avg * 100, 0, 100);
+	}
+	/**
+	* I/O ratio sub-score: lower ratio = better = higher score.
+	* Formula: clamp(100 - (avgIoRatio - 1) × 20, 0, 100)
+	*
+	* At avgIoRatio=1: score=80 (equal input/output tokens)
+	* At avgIoRatio=5: score=20
+	* At avgIoRatio≥6: clamped to 0
+	*/
+	_computeIoRatioSubScore(turns) {
+		const avg = this._computeAvgIoRatio(turns);
+		return this._clamp(100 - (avg - 1) * 20, 0, 100);
+	}
+	/**
+	* Context management sub-score: penalizes context spike frequency.
+	* Formula: clamp(100 - spikeRatio × 100, 0, 100)
+	* where spikeRatio = contextSpikeCount / max(totalTurns, 1)
+	*/
+	_computeContextManagementSubScore(turns) {
+		const totalTurns = Math.max(turns.length, 1);
+		const spikeCount = turns.filter((t) => t.isContextSpike).length;
+		const spikeRatio = spikeCount / totalTurns;
+		return this._clamp(100 - spikeRatio * 100, 0, 100);
+	}
+	_computeAvgCacheHitRate(turns) {
+		if (turns.length === 0) return 0;
+		const sum = turns.reduce((acc, t) => acc + t.cacheHitRate, 0);
+		return sum / turns.length;
+	}
+	/**
+	* Average I/O ratio: inputTokens / max(outputTokens, 1) per turn.
+	*/
+	_computeAvgIoRatio(turns) {
+		if (turns.length === 0) return 0;
+		const sum = turns.reduce((acc, t) => acc + t.inputTokens / Math.max(t.outputTokens, 1), 0);
+		return sum / turns.length;
+	}
+	/**
+	* Group turns by model, computing per-group efficiency metrics.
+	* Turns with null/undefined model are grouped under "unknown".
+	*/
+	_buildPerModelBreakdown(turns) {
+		const groups = new Map();
+		for (const turn of turns) {
+			const key = turn.model != null && turn.model !== "" ? turn.model : "unknown";
+			const existing = groups.get(key);
+			if (existing !== void 0) existing.push(turn);
+			else groups.set(key, [turn]);
+		}
+		const result = [];
+		for (const [model, groupTurns] of groups) {
+			const cacheHitRate = groupTurns.reduce((acc, t) => acc + t.cacheHitRate, 0) / groupTurns.length;
+			const avgIoRatio = groupTurns.reduce((acc, t) => acc + t.inputTokens / Math.max(t.outputTokens, 1), 0) / groupTurns.length;
+			const totalCostUsd = groupTurns.reduce((acc, t) => acc + t.costUsd, 0);
+			const totalOutputTokens = groupTurns.reduce((acc, t) => acc + t.outputTokens, 0);
+			const costPer1KOutputTokens = totalCostUsd / Math.max(totalOutputTokens, 1) * 1e3;
+			result.push({
+				model,
+				cacheHitRate,
+				avgIoRatio,
+				costPer1KOutputTokens
+			});
+		}
+		return result;
+	}
+	/**
+	* Group turns by source, computing a per-group composite score using the
+	* same formula as the overall score. Sources with zero turns are excluded.
+	*/
+	_buildPerSourceBreakdown(turns) {
+		const groups = new Map();
+		for (const turn of turns) {
+			const key = turn.source;
+			const existing = groups.get(key);
+			if (existing !== void 0) existing.push(turn);
+			else groups.set(key, [turn]);
+		}
+		const result = [];
+		for (const [source, groupTurns] of groups) {
+			if (groupTurns.length === 0) continue;
+			const cacheHitSub = this._computeCacheHitSubScoreForGroup(groupTurns);
+			const ioRatioSub = this._computeIoRatioSubScoreForGroup(groupTurns);
+			const contextSub = this._computeContextManagementSubScoreForGroup(groupTurns);
+			const compositeScore = Math.round(cacheHitSub * .4 + ioRatioSub * .3 + contextSub * .3);
+			result.push({
+				source,
+				compositeScore,
+				turnCount: groupTurns.length
+			});
+		}
+		return result;
+	}
+	_computeCacheHitSubScoreForGroup(turns) {
+		if (turns.length === 0) return 0;
+		const avg = turns.reduce((acc, t) => acc + t.cacheHitRate, 0) / turns.length;
+		return this._clamp(avg * 100, 0, 100);
+	}
+	_computeIoRatioSubScoreForGroup(turns) {
+		if (turns.length === 0) return 0;
+		const avg = turns.reduce((acc, t) => acc + t.inputTokens / Math.max(t.outputTokens, 1), 0) / turns.length;
+		return this._clamp(100 - (avg - 1) * 20, 0, 100);
+	}
+	_computeContextManagementSubScoreForGroup(turns) {
+		if (turns.length === 0) return 0;
+		const spikeCount = turns.filter((t) => t.isContextSpike).length;
+		const spikeRatio = spikeCount / turns.length;
+		return this._clamp(100 - spikeRatio * 100, 0, 100);
+	}
+	_clamp(value, min, max) {
+		return Math.max(min, Math.min(max, value));
+	}
+};
+
+//#endregion
+//#region src/modules/telemetry/categorizer.ts
+const EXACT_CATEGORY_MAP = new Map([
+	["read_file", "file_reads"],
+	["write_file", "tool_outputs"],
+	["bash", "tool_outputs"],
+	["tool_use", "tool_outputs"],
+	["tool_result", "tool_outputs"],
+	["system_prompt", "system_prompts"],
+	["human_turn", "user_prompts"],
+	["user_message", "user_prompts"],
+	["assistant_turn", "conversation_history"],
+	["assistant_message", "conversation_history"],
+	["search_files", "file_reads"],
+	["list_files", "file_reads"],
+	["run_command", "tool_outputs"],
+	["memory_read", "system_prompts"],
+	["web_fetch", "tool_outputs"]
+]);
+const PREFIX_PATTERNS = [
+	{
+		pattern: /^(bash|exec|run|spawn)/i,
+		category: "tool_outputs"
+	},
+	{
+		pattern: /^(read|open|cat|head|tail).*file/i,
+		category: "file_reads"
+	},
+	{
+		pattern: /^(list|glob|find).*file/i,
+		category: "file_reads"
+	},
+	{
+		pattern: /^tool/i,
+		category: "tool_outputs"
+	},
+	{
+		pattern: /^system/i,
+		category: "system_prompts"
+	},
+	{
+		pattern: /^(human|user)/i,
+		category: "user_prompts"
+	},
+	{
+		pattern: /^(assistant|ai|model)/i,
+		category: "conversation_history"
+	}
+];
+/** All six semantic categories in a stable order for zero-fill initialisation. */
+const ALL_CATEGORIES = [
+	"tool_outputs",
+	"file_reads",
+	"system_prompts",
+	"conversation_history",
+	"user_prompts",
+	"other"
+];
+var Categorizer = class {
+	_logger;
+	constructor(logger$26) {
+		this._logger = logger$26;
+	}
+	/**
+	* Classify an operation into a SemanticCategory using three-tier logic.
+	*
+	* @param operationName - Span operation name (e.g. 'read_file', 'bash')
+	* @param toolName      - Optional tool name; non-empty value overrides fallback to tool_outputs
+	*/
+	classify(operationName, toolName) {
+		const exact = EXACT_CATEGORY_MAP.get(operationName);
+		if (exact !== void 0) return exact;
+		for (const { pattern, category } of PREFIX_PATTERNS) if (pattern.test(operationName)) return category;
+		const lower = operationName.toLowerCase();
+		if (lower.includes("file") && (lower.includes("read") || lower.includes("open"))) return "file_reads";
+		if (lower.includes("system") || lower.includes("prompt")) return "system_prompts";
+		if (lower.includes("bash") || lower.includes("exec") || lower.includes("tool")) return "tool_outputs";
+		if (lower.includes("conversation") || lower.includes("history") || lower.includes("chat")) return "conversation_history";
+		if (lower.includes("user") || lower.includes("human")) return "user_prompts";
+		if (toolName !== void 0 && toolName.length > 0) return "tool_outputs";
+		return "other";
+	}
+	/**
+	* Detect whether a category's token consumption is growing, stable, or shrinking
+	* by comparing first-half vs second-half turn attribution.
+	*
+	* @param categorySpans - Spans already classified into this category
+	* @param turns         - Full turn sequence for the story
+	*/
+	computeTrend(categorySpans, turns) {
+		if (turns.length < 2) return "stable";
+		const spanTurnMap = new Map();
+		for (let i = 0; i < turns.length; i++) {
+			const turn = turns[i];
+			spanTurnMap.set(turn.spanId, i);
+			for (const child of turn.childSpans) spanTurnMap.set(child.spanId, i);
+		}
+		const half = Math.floor(turns.length / 2);
+		let firstHalfTokens = 0;
+		let secondHalfTokens = 0;
+		for (const span of categorySpans) {
+			const turnIdx = spanTurnMap.has(span.spanId) ? spanTurnMap.get(span.spanId) : attributeSpanToTurnIndex(span.startTime, turns);
+			const tokens = span.inputTokens + span.outputTokens;
+			if (turnIdx < half) firstHalfTokens += tokens;
+			else secondHalfTokens += tokens;
+		}
+		if (firstHalfTokens === 0 && secondHalfTokens === 0) return "stable";
+		if (firstHalfTokens === 0) return "growing";
+		if (secondHalfTokens > 1.2 * firstHalfTokens) return "growing";
+		if (secondHalfTokens < .8 * firstHalfTokens) return "shrinking";
+		return "stable";
+	}
+	/**
+	* Compute per-category token statistics for a complete set of spans.
+	*
+	* All six SemanticCategory values are always present in the result (zero-token
+	* categories are included with totalTokens: 0).  Results are sorted by
+	* totalTokens descending.
+	*
+	* @param spans - All NormalizedSpans for the story
+	* @param turns - TurnAnalysis sequence (may be empty)
+	*/
+	computeCategoryStats(spans, turns) {
+		const grandTotal = spans.reduce((sum, s) => sum + s.inputTokens + s.outputTokens, 0);
+		const buckets = new Map();
+		for (const cat of ALL_CATEGORIES) buckets.set(cat, []);
+		for (const span of spans) {
+			const toolName = extractToolNameFromSpan(span);
+			const cat = this.classify(span.operationName ?? span.name, toolName);
+			buckets.get(cat).push(span);
+		}
+		const results = ALL_CATEGORIES.map((category) => {
+			const catSpans = buckets.get(category);
+			const totalTokens = catSpans.reduce((sum, s) => sum + s.inputTokens + s.outputTokens, 0);
+			const eventCount = catSpans.length;
+			const percentage = grandTotal > 0 ? Math.round(totalTokens / grandTotal * 100 * 1e3) / 1e3 : 0;
+			const avgTokensPerEvent = eventCount > 0 ? totalTokens / eventCount : 0;
+			const trend = this.computeTrend(catSpans, turns);
+			return {
+				category,
+				totalTokens,
+				percentage,
+				eventCount,
+				avgTokensPerEvent,
+				trend
+			};
+		});
+		this._logger.debug({
+			categories: results.length,
+			grandTotal
+		}, "Computed category stats");
+		return results.sort((a, b) => b.totalTokens - a.totalTokens);
+	}
+};
+/**
+* Binary search: find the index of the last turn whose timestamp ≤ spanStartTime.
+* Returns 0 if no turn precedes the span.
+*/
+function attributeSpanToTurnIndex(spanStartTime, turns) {
+	let lo = 0;
+	let hi = turns.length - 1;
+	let result = 0;
+	while (lo <= hi) {
+		const mid = lo + hi >> 1;
+		if (turns[mid].timestamp <= spanStartTime) {
+			result = mid;
+			lo = mid + 1;
+		} else hi = mid - 1;
+	}
+	return result;
+}
+/**
+* Extract a tool name from a span's attributes, checking known attribute keys
+* in priority order.
+*/
+function extractToolNameFromSpan(span) {
+	if (!span.attributes) return void 0;
+	const attrs = span.attributes;
+	const name = attrs["tool.name"] || attrs["llm.tool.name"] || attrs["claude.tool_name"];
+	return name || void 0;
+}
+
+//#endregion
+//#region src/modules/telemetry/consumer-analyzer.ts
+var ConsumerAnalyzer = class {
+	_categorizer;
+	_logger;
+	constructor(categorizer, logger$26) {
+		this._categorizer = categorizer;
+		this._logger = logger$26;
+	}
+	/**
+	* Group spans by consumer key, rank by totalTokens descending, and return
+	* ConsumerStats for each non-zero-token group.
+	*
+	* @param spans - All NormalizedSpans for the story
+	*/
+	analyze(spans) {
+		if (spans.length === 0) return [];
+		const grandTotal = spans.reduce((sum, s) => sum + s.inputTokens + s.outputTokens, 0);
+		const groups = new Map();
+		for (const span of spans) {
+			const key = this._buildConsumerKey(span);
+			const existing = groups.get(key);
+			if (existing !== void 0) existing.push(span);
+			else groups.set(key, [span]);
+		}
+		const results = [];
+		for (const [consumerKey, groupSpans] of groups) {
+			const totalTokens = groupSpans.reduce((sum, s) => sum + s.inputTokens + s.outputTokens, 0);
+			if (totalTokens === 0) continue;
+			const percentage = grandTotal > 0 ? Math.round(totalTokens / grandTotal * 100 * 1e3) / 1e3 : 0;
+			const eventCount = groupSpans.length;
+			const firstSpan = groupSpans[0];
+			const toolName = this._extractToolName(firstSpan);
+			const operationName = firstSpan.operationName ?? firstSpan.name ?? "unknown";
+			const category = this._categorizer.classify(operationName, toolName);
+			const sorted = groupSpans.slice().sort((a, b) => b.inputTokens + b.outputTokens - (a.inputTokens + a.outputTokens));
+			const topInvocations = sorted.slice(0, 20).map((s) => ({
+				spanId: s.spanId,
+				name: s.name,
+				toolName: this._extractToolName(s),
+				totalTokens: s.inputTokens + s.outputTokens,
+				inputTokens: s.inputTokens,
+				outputTokens: s.outputTokens
+			}));
+			results.push({
+				consumerKey,
+				category,
+				totalTokens,
+				percentage,
+				eventCount,
+				topInvocations
+			});
+		}
+		this._logger.debug({
+			consumers: results.length,
+			grandTotal
+		}, "Computed consumer stats");
+		return results.sort((a, b) => b.totalTokens - a.totalTokens);
+	}
+	/**
+	* Build a stable, collision-resistant consumer key from a span.
+	* Format: `operationName|toolName` (tool part is empty string if absent).
+	*/
+	_buildConsumerKey(span) {
+		const operationPart = (span.operationName ?? span.name ?? "unknown").slice(0, 200);
+		const toolPart = (this._extractToolName(span) ?? "").slice(0, 100);
+		return `${operationPart}|${toolPart}`;
+	}
+	/**
+	* Extract a tool name from span attributes, checking three known attribute keys
+	* in priority order.
+	*/
+	_extractToolName(span) {
+		if (!span.attributes) return void 0;
+		const attrs = span.attributes;
+		const name = attrs["tool.name"] || attrs["llm.tool.name"] || attrs["claude.tool_name"];
+		return name || void 0;
+	}
+};
+
 //#endregion
 //#region src/modules/implementation-orchestrator/orchestrator-impl.ts
 function createPauseGate() {
@@ -8974,8 +10135,8 @@ function buildTargetedFilesContent(issueList) {
 * @returns A fully-configured ImplementationOrchestrator ready to call run()
 */
 function createImplementationOrchestrator(deps) {
-	const { db, pack, contextCompiler, dispatcher, eventBus, config, projectRoot, tokenCeilings, stateStore } = deps;
-	const logger$24 = createLogger("implementation-orchestrator");
+	const { db, pack, contextCompiler, dispatcher, eventBus, config, projectRoot, tokenCeilings, stateStore, telemetryPersistence, ingestionServer } = deps;
+	const logger$26 = createLogger("implementation-orchestrator");
 	let _state = "IDLE";
 	let _startedAt;
 	let _completedAt;
@@ -8995,6 +10156,7 @@ function createImplementationOrchestrator(deps) {
 	const _storyDispatches = new Map();
 	let _maxConcurrentActual = 0;
 	let _contractMismatches;
+	let _otlpEndpoint;
 	const _stateStoreCache = new Map();
 	const MEMORY_PRESSURE_BACKOFF_MS = [
 		3e4,
@@ -9020,7 +10182,7 @@ function createImplementationOrchestrator(deps) {
 		const nowMs = Date.now();
 		for (const [phase, startMs] of starts) {
 			const endMs = ends?.get(phase);
-			if (endMs === void 0) logger$24.warn({
+			if (endMs === void 0) logger$26.warn({
 				storyKey,
 				phase
 			}, "Phase has no end time — story may have errored mid-phase. Duration capped to now() and may be inflated.");
@@ -9067,7 +10229,7 @@ function createImplementationOrchestrator(deps) {
 				recordedAt: completedAt,
 				timestamp: completedAt
 			}).catch((storeErr) => {
-				logger$24.warn({
+				logger$26.warn({
 					err: storeErr,
 					storyKey
 				}, "Failed to record metric to StateStore (best-effort)");
@@ -9089,7 +10251,7 @@ function createImplementationOrchestrator(deps) {
 					rationale: `Story ${storyKey} completed with result=${result} in ${wallClockSeconds}s. Tokens: ${tokenAgg.input}+${tokenAgg.output}. Review cycles: ${reviewCycles}.`
 				});
 			} catch (decisionErr) {
-				logger$24.warn({
+				logger$26.warn({
 					err: decisionErr,
 					storyKey
 				}, "Failed to write story-metrics decision (best-effort)");
@@ -9117,13 +10279,13 @@ function createImplementationOrchestrator(deps) {
 					dispatches: _storyDispatches.get(storyKey) ?? 0
 				});
 			} catch (emitErr) {
-				logger$24.warn({
+				logger$26.warn({
 					err: emitErr,
 					storyKey
 				}, "Failed to emit story:metrics event (best-effort)");
 			}
 		} catch (err) {
-			logger$24.warn({
+			logger$26.warn({
 				err,
 				storyKey
 			}, "Failed to write story metrics (best-effort)");
@@ -9152,7 +10314,7 @@ function createImplementationOrchestrator(deps) {
 				rationale: `Story ${storyKey} ${outcome} after ${reviewCycles} review cycle(s).`
 			});
 		} catch (err) {
-			logger$24.warn({
+			logger$26.warn({
 				err,
 				storyKey
 			}, "Failed to write story-outcome decision (best-effort)");
@@ -9178,7 +10340,7 @@ function createImplementationOrchestrator(deps) {
 				rationale: `Escalation diagnosis for ${payload.storyKey}: ${diagnosis.recommendedAction} — ${diagnosis.rationale}`
 			});
 		} catch (err) {
-			logger$24.warn({
+			logger$26.warn({
 				err,
 				storyKey: payload.storyKey
 			}, "Failed to persist escalation diagnosis (best-effort)");
@@ -9227,7 +10389,7 @@ function createImplementationOrchestrator(deps) {
 		const existing = _stories.get(storyKey);
 		if (existing !== void 0) {
 			Object.assign(existing, updates);
-			persistStoryState(storyKey, existing).catch((err) => logger$24.warn({
+			persistStoryState(storyKey, existing).catch((err) => logger$26.warn({
 				err,
 				storyKey
 			}, "StateStore write failed after updateStory"));
@@ -9236,12 +10398,12 @@ function createImplementationOrchestrator(deps) {
 					storyKey,
 					conflict: err
 				});
-				else logger$24.warn({
+				else logger$26.warn({
 					err,
 					storyKey
 				}, "mergeStory failed");
 			});
-			else if (updates.phase === "ESCALATED" || updates.phase === "FAILED") stateStore?.rollbackStory(storyKey).catch((err) => logger$24.warn({
+			else if (updates.phase === "ESCALATED") stateStore?.rollbackStory(storyKey).catch((err) => logger$26.warn({
 				err,
 				storyKey
 			}, "rollbackStory failed — branch may persist"));
@@ -9268,7 +10430,7 @@ function createImplementationOrchestrator(deps) {
 			};
 			await stateStore.setStoryState(storyKey, record);
 		} catch (err) {
-			logger$24.warn({
+			logger$26.warn({
 				err,
 				storyKey
 			}, "StateStore.setStoryState failed (best-effort)");
@@ -9284,7 +10446,7 @@ function createImplementationOrchestrator(deps) {
 				token_usage_json: serialized
 			});
 		} catch (err) {
-			logger$24.warn({ err }, "Failed to persist orchestrator state");
+			logger$26.warn({ err }, "Failed to persist orchestrator state");
 		}
 	}
 	function recordProgress() {
@@ -9331,7 +10493,7 @@ function createImplementationOrchestrator(deps) {
 				}
 				if (childActive) {
 					_lastProgressTs = Date.now();
-					logger$24.debug({
+					logger$26.debug({
 						storyKey: key,
 						phase: s.phase,
 						childPids
@@ -9340,7 +10502,7 @@ function createImplementationOrchestrator(deps) {
 				}
 				_stalledStories.add(key);
 				_storiesWithStall.add(key);
-				logger$24.warn({
+				logger$26.warn({
 					storyKey: key,
 					phase: s.phase,
 					elapsedMs: elapsed,
@@ -9385,7 +10547,7 @@ function createImplementationOrchestrator(deps) {
 		for (let attempt = 0; attempt < MEMORY_PRESSURE_BACKOFF_MS.length; attempt++) {
 			const memState = dispatcher.getMemoryState();
 			if (!memState.isPressured) return true;
-			logger$24.warn({
+			logger$26.warn({
 				storyKey,
 				freeMB: memState.freeMB,
 				thresholdMB: memState.thresholdMB,
@@ -9405,11 +10567,11 @@ function createImplementationOrchestrator(deps) {
 	* exhausted retries the story is ESCALATED.
 	*/
 	async function processStory(storyKey) {
-		logger$24.info({ storyKey }, "Processing story");
+		logger$26.info({ storyKey }, "Processing story");
 		{
 			const memoryOk = await checkMemoryPressure(storyKey);
 			if (!memoryOk) {
-				logger$24.warn({ storyKey }, "Memory pressure exhausted — escalating story without dispatch");
+				logger$26.warn({ storyKey }, "Memory pressure exhausted — escalating story without dispatch");
 				const memPressureState = {
 					phase: "ESCALATED",
 					reviewCycles: 0,
@@ -9418,7 +10580,7 @@ function createImplementationOrchestrator(deps) {
 					completedAt: new Date().toISOString()
 				};
 				_stories.set(storyKey, memPressureState);
-				persistStoryState(storyKey, memPressureState).catch((err) => logger$24.warn({
+				persistStoryState(storyKey, memPressureState).catch((err) => logger$26.warn({
 					err,
 					storyKey
 				}, "StateStore write failed after memory-pressure escalation"));
@@ -9435,7 +10597,7 @@ function createImplementationOrchestrator(deps) {
 		}
 		await waitIfPaused();
 		if (_state !== "RUNNING") return;
-		stateStore?.branchForStory(storyKey).catch((err) => logger$24.warn({
+		stateStore?.branchForStory(storyKey).catch((err) => logger$26.warn({
 			err,
 			storyKey
 		}, "branchForStory failed — continuing without branch isolation"));
@@ -9452,14 +10614,14 @@ function createImplementationOrchestrator(deps) {
 			if (match) {
 				const candidatePath = join$1(artifactsDir, match);
 				const validation = await isValidStoryFile(candidatePath);
-				if (!validation.valid) logger$24.warn({
+				if (!validation.valid) logger$26.warn({
 					storyKey,
 					storyFilePath: candidatePath,
 					reason: validation.reason
 				}, `Existing story file for ${storyKey} is invalid (${validation.reason}) — re-creating`);
 				else {
 					storyFilePath = candidatePath;
-					logger$24.info({
+					logger$26.info({
 						storyKey,
 						storyFilePath
 					}, "Found existing story file — skipping create-story");
@@ -9485,7 +10647,8 @@ function createImplementationOrchestrator(deps) {
 				contextCompiler,
 				dispatcher,
 				projectRoot,
-				tokenCeilings
+				tokenCeilings,
+				otlpEndpoint: _otlpEndpoint
 			}, {
 				epicId: storyKey.split("-")[0] ?? storyKey,
 				storyKey,
@@ -9576,14 +10739,14 @@ function createImplementationOrchestrator(deps) {
 						...contract.transport !== void 0 ? { transport: contract.transport } : {}
 					})
 				});
-				logger$24.info({
+				logger$26.info({
 					storyKey,
 					contractCount: contracts.length,
 					contracts
 				}, "Stored interface contract declarations");
 			}
 		} catch (err) {
-			logger$24.warn({
+			logger$26.warn({
 				storyKey,
 				error: err instanceof Error ? err.message : String(err)
 			}, "Failed to parse interface contracts — continuing without contract declarations");
@@ -9601,17 +10764,18 @@ function createImplementationOrchestrator(deps) {
 				contextCompiler,
 				dispatcher,
 				projectRoot,
-				tokenCeilings
+				tokenCeilings,
+				otlpEndpoint: _otlpEndpoint
 			}, {
 				storyKey,
 				storyFilePath: storyFilePath ?? "",
 				pipelineRunId: config.pipelineRunId ?? ""
 			});
 			testPlanPhaseResult = testPlanResult.result;
-			if (testPlanResult.result === "success") logger$24.info({ storyKey }, "Test plan generated successfully");
-			else logger$24.warn({ storyKey }, "Test planning returned failed result — proceeding to dev-story without test plan");
+			if (testPlanResult.result === "success") logger$26.info({ storyKey }, "Test plan generated successfully");
+			else logger$26.warn({ storyKey }, "Test planning returned failed result — proceeding to dev-story without test plan");
 		} catch (err) {
-			logger$24.warn({
+			logger$26.warn({
 				storyKey,
 				err
 			}, "Test planning failed — proceeding to dev-story without test plan");
@@ -9635,7 +10799,7 @@ function createImplementationOrchestrator(deps) {
 			try {
 				storyContentForAnalysis = await readFile$1(storyFilePath ?? "", "utf-8");
 			} catch (err) {
-				logger$24.error({
+				logger$26.error({
 					storyKey,
 					storyFilePath,
 					error: err instanceof Error ? err.message : String(err)
@@ -9643,7 +10807,7 @@ function createImplementationOrchestrator(deps) {
 			}
 			const analysis = analyzeStoryComplexity(storyContentForAnalysis);
 			const batches = planTaskBatches(analysis);
-			logger$24.info({
+			logger$26.info({
 				storyKey,
 				estimatedScope: analysis.estimatedScope,
 				batchCount: batches.length,
@@ -9661,7 +10825,7 @@ function createImplementationOrchestrator(deps) {
 					if (_state !== "RUNNING") break;
 					const taskScope = batch.taskIds.map((id, i) => `T${id}: ${batch.taskTitles[i] ?? ""}`).join("\n");
 					const priorFiles = allFilesModified.size > 0 ? Array.from(allFilesModified) : void 0;
-					logger$24.info({
+					logger$26.info({
 						storyKey,
 						batchIndex: batch.batchIndex,
 						taskCount: batch.taskIds.length
@@ -9676,7 +10840,8 @@ function createImplementationOrchestrator(deps) {
 							contextCompiler,
 							dispatcher,
 							projectRoot,
-							tokenCeilings
+							tokenCeilings,
+							otlpEndpoint: _otlpEndpoint
 						}, {
 							storyKey,
 							storyFilePath: storyFilePath ?? "",
@@ -9686,7 +10851,7 @@ function createImplementationOrchestrator(deps) {
 						});
 					} catch (batchErr) {
 						const errMsg = batchErr instanceof Error ? batchErr.message : String(batchErr);
-						logger$24.warn({
+						logger$26.warn({
 							storyKey,
 							batchIndex: batch.batchIndex,
 							error: errMsg
@@ -9706,7 +10871,7 @@ function createImplementationOrchestrator(deps) {
 						filesModified: batchFilesModified,
 						result: batchResult.result === "success" ? "success" : "failed"
 					};
-					logger$24.info(batchMetrics, "Batch dev-story metrics");
+					logger$26.info(batchMetrics, "Batch dev-story metrics");
 					for (const f of batchFilesModified) allFilesModified.add(f);
 					if (batchFilesModified.length > 0) batchFileGroups.push({
 						batchIndex: batch.batchIndex,
@@ -9728,13 +10893,13 @@ function createImplementationOrchestrator(deps) {
 							})
 						});
 					} catch (tokenErr) {
-						logger$24.warn({
+						logger$26.warn({
 							storyKey,
 							batchIndex: batch.batchIndex,
 							err: tokenErr
 						}, "Failed to record batch token usage");
 					}
-					if (batchResult.result === "failed") logger$24.warn({
+					if (batchResult.result === "failed") logger$26.warn({
 						storyKey,
 						batchIndex: batch.batchIndex,
 						error: batchResult.error
@@ -9756,7 +10921,8 @@ function createImplementationOrchestrator(deps) {
 					contextCompiler,
 					dispatcher,
 					projectRoot,
-					tokenCeilings
+					tokenCeilings,
+					otlpEndpoint: _otlpEndpoint
 				}, {
 					storyKey,
 					storyFilePath: storyFilePath ?? "",
@@ -9770,7 +10936,7 @@ function createImplementationOrchestrator(deps) {
 				});
 				persistState();
 				if (devResult.result === "success") devStoryWasSuccess = true;
-				else logger$24.warn({
+				else logger$26.warn({
 					storyKey,
 					error: devResult.error,
 					filesModified: devFilesModified.length
@@ -9798,7 +10964,7 @@ function createImplementationOrchestrator(deps) {
 		if (devStoryWasSuccess) {
 			gitDiffFiles = checkGitDiffFiles(projectRoot ?? process.cwd());
 			if (gitDiffFiles.length === 0) {
-				logger$24.warn({ storyKey }, "Zero-diff detected after COMPLETE dev-story — no file changes in git working tree");
+				logger$26.warn({ storyKey }, "Zero-diff detected after COMPLETE dev-story — no file changes in git working tree");
 				eventBus.emit("orchestrator:zero-diff-escalation", {
 					storyKey,
 					reason: "zero-diff-on-complete"
@@ -9829,7 +10995,7 @@ function createImplementationOrchestrator(deps) {
 			});
 			if (buildVerifyResult.status === "passed") {
 				eventBus.emit("story:build-verification-passed", { storyKey });
-				logger$24.info({ storyKey }, "Build verification passed");
+				logger$26.info({ storyKey }, "Build verification passed");
 			} else if (buildVerifyResult.status === "failed" || buildVerifyResult.status === "timeout") {
 				const truncatedOutput = (buildVerifyResult.output ?? "").slice(0, 2e3);
 				const reason = buildVerifyResult.reason ?? "build-verification-failed";
@@ -9838,7 +11004,7 @@ function createImplementationOrchestrator(deps) {
 					exitCode: buildVerifyResult.exitCode ?? 1,
 					output: truncatedOutput
 				});
-				logger$24.warn({
+				logger$26.warn({
 					storyKey,
 					reason,
 					exitCode: buildVerifyResult.exitCode
@@ -9868,7 +11034,7 @@ function createImplementationOrchestrator(deps) {
 					storyKey
 				});
 				if (icResult.potentiallyAffectedTests.length > 0) {
-					logger$24.warn({
+					logger$26.warn({
 						storyKey,
 						modifiedInterfaces: icResult.modifiedInterfaces,
 						potentiallyAffectedTests: icResult.potentiallyAffectedTests
@@ -9914,7 +11080,7 @@ function createImplementationOrchestrator(deps) {
 						"NEEDS_MAJOR_REWORK": 2
 					};
 					for (const group of batchFileGroups) {
-						logger$24.info({
+						logger$26.info({
 							storyKey,
 							batchIndex: group.batchIndex,
 							fileCount: group.files.length
@@ -9926,7 +11092,8 @@ function createImplementationOrchestrator(deps) {
 							contextCompiler,
 							dispatcher,
 							projectRoot,
-							tokenCeilings
+							tokenCeilings,
+							otlpEndpoint: _otlpEndpoint
 						}, {
 							storyKey,
 							storyFilePath: storyFilePath ?? "",
@@ -9952,7 +11119,7 @@ function createImplementationOrchestrator(deps) {
 						rawOutput: lastRawOutput,
 						tokenUsage: aggregateTokens
 					};
-					logger$24.info({
+					logger$26.info({
 						storyKey,
 						batchCount: batchFileGroups.length,
 						verdict: worstVerdict,
@@ -9966,7 +11133,8 @@ function createImplementationOrchestrator(deps) {
 						contextCompiler,
 						dispatcher,
 						projectRoot,
-						tokenCeilings
+						tokenCeilings,
+						otlpEndpoint: _otlpEndpoint
 					}, {
 						storyKey,
 						storyFilePath: storyFilePath ?? "",
@@ -9979,7 +11147,7 @@ function createImplementationOrchestrator(deps) {
 				const isPhantomReview = reviewResult.dispatchFailed === true || reviewResult.verdict !== "SHIP_IT" && reviewResult.verdict !== "LGTM_WITH_NOTES" && (reviewResult.issue_list === void 0 || reviewResult.issue_list.length === 0) && reviewResult.error !== void 0;
 				if (isPhantomReview && !timeoutRetried) {
 					timeoutRetried = true;
-					logger$24.warn({
+					logger$26.warn({
 						storyKey,
 						reviewCycles,
 						error: reviewResult.error
@@ -9989,7 +11157,7 @@ function createImplementationOrchestrator(deps) {
 				verdict = reviewResult.verdict;
 				issueList = reviewResult.issue_list ?? [];
 				if (verdict === "NEEDS_MAJOR_REWORK" && reviewCycles > 0 && previousIssueList.length > 0 && issueList.length < previousIssueList.length) {
-					logger$24.info({
+					logger$26.info({
 						storyKey,
 						originalVerdict: verdict,
 						issuesBefore: previousIssueList.length,
@@ -10025,7 +11193,7 @@ function createImplementationOrchestrator(deps) {
 					if (_decomposition !== void 0) parts.push(`decomposed: ${_decomposition.batchCount} batches`);
 					parts.push(`${fileCount} files`);
 					parts.push(`${totalTokensK} tokens`);
-					logger$24.info({
+					logger$26.info({
 						storyKey,
 						verdict,
 						agentVerdict: reviewResult.agentVerdict
@@ -10074,13 +11242,58 @@ function createImplementationOrchestrator(deps) {
 						}),
 						rationale: `Advisory notes from LGTM_WITH_NOTES review of ${storyKey}`
 					});
-					logger$24.info({ storyKey }, "Advisory notes persisted to decision store");
+					logger$26.info({ storyKey }, "Advisory notes persisted to decision store");
 				} catch (advisoryErr) {
-					logger$24.warn({
+					logger$26.warn({
 						storyKey,
 						error: advisoryErr instanceof Error ? advisoryErr.message : String(advisoryErr)
 					}, "Failed to persist advisory notes (best-effort)");
 				}
+				if (telemetryPersistence !== void 0) try {
+					const turns = await telemetryPersistence.getTurnAnalysis(storyKey);
+					if (turns.length > 0) {
+						const scorer = new EfficiencyScorer(logger$26);
+						const effScore = scorer.score(storyKey, turns);
+						await telemetryPersistence.storeEfficiencyScore(effScore);
+						logger$26.info({
+							storyKey,
+							compositeScore: effScore.compositeScore,
+							modelCount: effScore.perModelBreakdown.length
+						}, "Efficiency score computed and persisted");
+					} else logger$26.debug({ storyKey }, "No turn analysis data available — skipping efficiency scoring");
+				} catch (effErr) {
+					logger$26.warn({
+						storyKey,
+						error: effErr instanceof Error ? effErr.message : String(effErr)
+					}, "Efficiency scoring failed — story verdict unchanged");
+				}
+				if (telemetryPersistence !== void 0) try {
+					const turns = await telemetryPersistence.getTurnAnalysis(storyKey);
+					const spans = [];
+					if (spans.length === 0) logger$26.debug({ storyKey }, "No spans for telemetry categorization — skipping");
+					else {
+						const categorizer = new Categorizer(logger$26);
+						const consumerAnalyzer = new ConsumerAnalyzer(categorizer, logger$26);
+						const categoryStats = categorizer.computeCategoryStats(spans, turns);
+						const consumerStats = consumerAnalyzer.analyze(spans);
+						await telemetryPersistence.storeCategoryStats(storyKey, categoryStats);
+						await telemetryPersistence.storeConsumerStats(storyKey, consumerStats);
+						const growingCount = categoryStats.filter((c) => c.trend === "growing").length;
+						const topCategory = categoryStats[0]?.category ?? "none";
+						const topConsumer = consumerStats[0]?.consumerKey ?? "none";
+						logger$26.info({
+							storyKey,
+							topCategory,
+							topConsumer,
+							growingCount
+						}, "Semantic categorization and consumer analysis complete");
+					}
+				} catch (catErr) {
+					logger$26.warn({
+						storyKey,
+						error: catErr instanceof Error ? catErr.message : String(catErr)
+					}, "Semantic categorization failed — story verdict unchanged");
+				}
 				try {
 					const expansionResult = await runTestExpansion({
 						db,
@@ -10088,7 +11301,8 @@ function createImplementationOrchestrator(deps) {
 						contextCompiler,
 						dispatcher,
 						projectRoot,
-						tokenCeilings
+						tokenCeilings,
+						otlpEndpoint: _otlpEndpoint
 					}, {
 						storyKey,
 						storyFilePath: storyFilePath ?? "",
@@ -10096,7 +11310,7 @@ function createImplementationOrchestrator(deps) {
 						filesModified: devFilesModified,
 						workingDirectory: projectRoot
 					});
-					logger$24.debug({
+					logger$26.debug({
 						storyKey,
 						expansion_priority: expansionResult.expansion_priority,
 						coverage_gaps: expansionResult.coverage_gaps.length
@@ -10109,7 +11323,7 @@ function createImplementationOrchestrator(deps) {
 						value: JSON.stringify(expansionResult)
 					});
 				} catch (expansionErr) {
-					logger$24.warn({
+					logger$26.warn({
 						storyKey,
 						error: expansionErr instanceof Error ? expansionErr.message : String(expansionErr)
 					}, "Test expansion failed — story verdict unchanged");
@@ -10136,7 +11350,7 @@ function createImplementationOrchestrator(deps) {
 					persistState();
 					return;
 				}
-				logger$24.info({
+				logger$26.info({
 					storyKey,
 					reviewCycles: finalReviewCycles,
 					issueCount: issueList.length
@@ -10196,14 +11410,15 @@ function createImplementationOrchestrator(deps) {
 						fixPrompt = assembled.prompt;
 					} catch {
 						fixPrompt = `Fix story ${storyKey}: verdict=${verdict}, minor fixes needed`;
-						logger$24.warn({ storyKey }, "Failed to assemble auto-approve fix prompt, using fallback");
+						logger$26.warn({ storyKey }, "Failed to assemble auto-approve fix prompt, using fallback");
 					}
 					const handle = dispatcher.dispatch({
 						prompt: fixPrompt,
 						agent: "claude-code",
 						taskType: "minor-fixes",
 						workingDirectory: projectRoot,
-						...autoApproveMaxTurns !== void 0 ? { maxTurns: autoApproveMaxTurns } : {}
+						...autoApproveMaxTurns !== void 0 ? { maxTurns: autoApproveMaxTurns } : {},
+						..._otlpEndpoint !== void 0 ? { otlpEndpoint: _otlpEndpoint } : {}
 					});
 					const fixResult = await handle.result;
 					eventBus.emit("orchestrator:story-phase-complete", {
@@ -10214,9 +11429,9 @@ function createImplementationOrchestrator(deps) {
 							output: fixResult.tokenEstimate.output
 						} : void 0 }
 					});
-					if (fixResult.status === "timeout") logger$24.warn({ storyKey }, "Auto-approve fix timed out — approving anyway (issues were minor)");
+					if (fixResult.status === "timeout") logger$26.warn({ storyKey }, "Auto-approve fix timed out — approving anyway (issues were minor)");
 				} catch (err) {
-					logger$24.warn({
+					logger$26.warn({
 						storyKey,
 						err
 					}, "Auto-approve fix dispatch failed — approving anyway (issues were minor)");
@@ -10333,7 +11548,7 @@ function createImplementationOrchestrator(deps) {
 					fixPrompt = assembled.prompt;
 				} catch {
 					fixPrompt = `Fix story ${storyKey}: verdict=${verdict}, taskType=${taskType}`;
-					logger$24.warn({
+					logger$26.warn({
 						storyKey,
 						taskType
 					}, "Failed to assemble fix prompt, using fallback");
@@ -10346,14 +11561,16 @@ function createImplementationOrchestrator(deps) {
 					...fixModel !== void 0 ? { model: fixModel } : {},
 					outputSchema: DevStoryResultSchema,
 					...fixMaxTurns !== void 0 ? { maxTurns: fixMaxTurns } : {},
-					...projectRoot !== void 0 ? { workingDirectory: projectRoot } : {}
+					...projectRoot !== void 0 ? { workingDirectory: projectRoot } : {},
+					..._otlpEndpoint !== void 0 ? { otlpEndpoint: _otlpEndpoint } : {}
 				}) : dispatcher.dispatch({
 					prompt: fixPrompt,
 					agent: "claude-code",
 					taskType,
 					...fixModel !== void 0 ? { model: fixModel } : {},
 					...fixMaxTurns !== void 0 ? { maxTurns: fixMaxTurns } : {},
-					...projectRoot !== void 0 ? { workingDirectory: projectRoot } : {}
+					...projectRoot !== void 0 ? { workingDirectory: projectRoot } : {},
+					..._otlpEndpoint !== void 0 ? { otlpEndpoint: _otlpEndpoint } : {}
 				});
 				const fixResult = await handle.result;
 				eventBus.emit("orchestrator:story-phase-complete", {
@@ -10365,7 +11582,7 @@ function createImplementationOrchestrator(deps) {
 					} : void 0 }
 				});
 				if (fixResult.status === "timeout") {
-					logger$24.warn({
+					logger$26.warn({
 						storyKey,
 						taskType
 					}, "Fix dispatch timed out — escalating story");
@@ -10387,7 +11604,7 @@ function createImplementationOrchestrator(deps) {
 				}
 				if (fixResult.status === "failed") {
 					if (isMajorRework) {
-						logger$24.warn({
+						logger$26.warn({
 							storyKey,
 							exitCode: fixResult.exitCode
 						}, "Major rework dispatch failed — escalating story");
@@ -10407,14 +11624,14 @@ function createImplementationOrchestrator(deps) {
 						persistState();
 						return;
 					}
-					logger$24.warn({
+					logger$26.warn({
 						storyKey,
 						taskType,
 						exitCode: fixResult.exitCode
 					}, "Fix dispatch failed");
 				}
 			} catch (err) {
-				logger$24.warn({
+				logger$26.warn({
 					storyKey,
 					taskType,
 					err
@@ -10477,11 +11694,11 @@ function createImplementationOrchestrator(deps) {
 	}
 	async function run(storyKeys) {
 		if (_state === "RUNNING" || _state === "PAUSED") {
-			logger$24.warn({ state: _state }, "run() called while orchestrator is already running or paused — ignoring");
+			logger$26.warn({ state: _state }, "run() called while orchestrator is already running or paused — ignoring");
 			return getStatus();
 		}
 		if (_state === "COMPLETE") {
-			logger$24.warn({ state: _state }, "run() called on a COMPLETE orchestrator — ignoring");
+			logger$26.warn({ state: _state }, "run() called on a COMPLETE orchestrator — ignoring");
 			return getStatus();
 		}
 		_state = "RUNNING";
@@ -10502,7 +11719,7 @@ function createImplementationOrchestrator(deps) {
 		if (config.enableHeartbeat) startHeartbeat();
 		if (projectRoot !== void 0) {
 			const seedResult = seedMethodologyContext(db, projectRoot);
-			if (seedResult.decisionsCreated > 0) logger$24.info({
+			if (seedResult.decisionsCreated > 0) logger$26.info({
 				decisionsCreated: seedResult.decisionsCreated,
 				skippedCategories: seedResult.skippedCategories
 			}, "Methodology context seeded from planning artifacts");
@@ -10512,7 +11729,7 @@ function createImplementationOrchestrator(deps) {
 				await stateStore.initialize();
 				for (const key of storyKeys) {
 					const pendingState = _stories.get(key);
-					if (pendingState !== void 0) persistStoryState(key, pendingState).catch((err) => logger$24.warn({
+					if (pendingState !== void 0) persistStoryState(key, pendingState).catch((err) => logger$26.warn({
 						err,
 						storyKey: key
 					}, "StateStore write failed during PENDING init"));
@@ -10521,9 +11738,16 @@ function createImplementationOrchestrator(deps) {
 					const existingRecords = await stateStore.queryStories({});
 					for (const record of existingRecords) _stateStoreCache.set(record.storyKey, record);
 				} catch (err) {
-					logger$24.warn({ err }, "StateStore.queryStories() failed during init — status merge will be empty (best-effort)");
+					logger$26.warn({ err }, "StateStore.queryStories() failed during init — status merge will be empty (best-effort)");
 				}
 			}
+			if (ingestionServer !== void 0) {
+				await ingestionServer.start().catch((err) => logger$26.warn({ err }, "IngestionServer.start() failed — continuing without telemetry (best-effort)"));
+				try {
+					_otlpEndpoint = ingestionServer.getOtlpEnvVars().OTEL_EXPORTER_OTLP_ENDPOINT;
+					logger$26.info({ otlpEndpoint: _otlpEndpoint }, "OTLP telemetry ingestion active");
+				} catch {}
+			}
 			let contractDeclarations = [];
 			if (stateStore !== void 0) {
 				const allContractRecords = await stateStore.queryContracts();
@@ -10557,11 +11781,11 @@ function createImplementationOrchestrator(deps) {
 				}).filter((d) => d !== null);
 			}
 			const { batches, edges: contractEdges } = detectConflictGroupsWithContracts(storyKeys, { moduleMap: pack.manifest.conflictGroups }, contractDeclarations);
-			if (contractEdges.length > 0) logger$24.info({
+			if (contractEdges.length > 0) logger$26.info({
 				contractEdges,
 				edgeCount: contractEdges.length
 			}, "Contract dependency edges detected — applying contract-aware dispatch ordering");
-			logger$24.info({
+			logger$26.info({
 				storyCount: storyKeys.length,
 				groupCount: batches.reduce((sum, b) => sum + b.length, 0),
 				batchCount: batches.length,
@@ -10581,7 +11805,7 @@ function createImplementationOrchestrator(deps) {
 						exitCode,
 						output: truncatedOutput
 					});
-					logger$24.error({
+					logger$26.error({
 						exitCode,
 						reason: preFlightResult.reason
 					}, "Pre-flight build check failed — aborting pipeline before any story dispatch");
@@ -10590,7 +11814,7 @@ function createImplementationOrchestrator(deps) {
 					persistState();
 					return getStatus();
 				}
-				if (preFlightResult.status !== "skipped") logger$24.info("Pre-flight build check passed");
+				if (preFlightResult.status !== "skipped") logger$26.info("Pre-flight build check passed");
 			}
 			try {
 				for (const batchGroups of batches) await runWithConcurrency(batchGroups, config.maxConcurrency);
@@ -10599,7 +11823,7 @@ function createImplementationOrchestrator(deps) {
 				_state = "FAILED";
 				_completedAt = new Date().toISOString();
 				persistState();
-				logger$24.error({ err }, "Orchestrator failed with unhandled error");
+				logger$26.error({ err }, "Orchestrator failed with unhandled error");
 				return getStatus();
 			}
 			stopHeartbeat();
@@ -10615,11 +11839,11 @@ function createImplementationOrchestrator(deps) {
 						contractName: mismatch.contractName,
 						mismatchDescription: mismatch.mismatchDescription
 					});
-					logger$24.warn({
+					logger$26.warn({
 						mismatchCount: mismatches.length,
 						mismatches
 					}, "Post-sprint contract verification found mismatches — manual review required");
-				} else logger$24.info("Post-sprint contract verification passed — all declared contracts satisfied");
+				} else logger$26.info("Post-sprint contract verification passed — all declared contracts satisfied");
 				if (stateStore !== void 0) try {
 					const allContractsForVerification = await stateStore.queryContracts();
 					const verifiedAt = new Date().toISOString();
@@ -10648,12 +11872,12 @@ function createImplementationOrchestrator(deps) {
 						});
 						await stateStore.setContractVerification(sk, records);
 					}
-					logger$24.info({ storyCount: contractsByStory.size }, "Contract verification results persisted to StateStore");
+					logger$26.info({ storyCount: contractsByStory.size }, "Contract verification results persisted to StateStore");
 				} catch (persistErr) {
-					logger$24.warn({ err: persistErr }, "Failed to persist contract verification results to StateStore");
+					logger$26.warn({ err: persistErr }, "Failed to persist contract verification results to StateStore");
 				}
 			} catch (err) {
-				logger$24.error({ err }, "Post-sprint contract verification threw an error — skipping");
+				logger$26.error({ err }, "Post-sprint contract verification threw an error — skipping");
 			}
 			let completed = 0;
 			let escalated = 0;
@@ -10670,7 +11894,8 @@ function createImplementationOrchestrator(deps) {
 			persistState();
 			return getStatus();
 		} finally {
-			if (stateStore !== void 0) await stateStore.close().catch((err) => logger$24.warn({ err }, "StateStore.close() failed (best-effort)"));
+			if (stateStore !== void 0) await stateStore.close().catch((err) => logger$26.warn({ err }, "StateStore.close() failed (best-effort)"));
+			if (ingestionServer !== void 0) await ingestionServer.stop().catch((err) => logger$26.warn({ err }, "IngestionServer.stop() failed (best-effort)"));
 		}
 	}
 	function pause() {
@@ -10679,7 +11904,7 @@ function createImplementationOrchestrator(deps) {
 		_pauseGate = createPauseGate();
 		_state = "PAUSED";
 		eventBus.emit("orchestrator:paused", {});
-		logger$24.info("Orchestrator paused");
+		logger$26.info("Orchestrator paused");
 	}
 	function resume() {
 		if (_state !== "PAUSED") return;
@@ -10690,7 +11915,7 @@ function createImplementationOrchestrator(deps) {
 		}
 		_state = "RUNNING";
 		eventBus.emit("orchestrator:resumed", {});
-		logger$24.info("Orchestrator resumed");
+		logger$26.info("Orchestrator resumed");
 	}
 	return {
 		run,
@@ -10733,7 +11958,11 @@ function resolveStoryKeys(db, projectRoot, opts) {
 		const allContent = shardRows.map((r) => r.value).join("\n");
 		if (allContent.length > 0) keys = parseStoryKeysFromEpics(allContent);
 	} catch {}
-	if (keys.length === 0) keys = discoverPendingStoryKeys(projectRoot);
+	if (keys.length === 0) keys = discoverPendingStoryKeys(projectRoot, opts?.epicNumber);
+	if (opts?.epicNumber !== void 0 && keys.length > 0) {
+		const prefix = `${opts.epicNumber}-`;
+		keys = keys.filter((k) => k.startsWith(prefix));
+	}
 	if (opts?.filterCompleted === true && keys.length > 0) {
 		const completedKeys = getCompletedStoryKeys(db);
 		keys = keys.filter((k) => !completedKeys.has(k));
@@ -10781,21 +12010,33 @@ function parseStoryKeysFromEpics(content) {
 * @param projectRoot - Absolute path to the project root directory
 * @returns Sorted array of pending story keys in "N-M" format
 */
-function discoverPendingStoryKeys(projectRoot) {
+function discoverPendingStoryKeys(projectRoot, epicNumber) {
 	let allKeys = [];
-	const epicsPath = findEpicsFile(projectRoot);
-	if (epicsPath !== void 0) try {
-		const content = readFileSync$1(epicsPath, "utf-8");
-		allKeys = parseStoryKeysFromEpics(content);
-	} catch {}
-	if (allKeys.length === 0) {
+	if (epicNumber !== void 0) {
 		const epicFiles = findEpicFiles(projectRoot);
-		for (const epicFile of epicFiles) try {
+		const targetPattern = new RegExp(`^epic-${epicNumber}[^0-9]`);
+		const matched = epicFiles.filter((f) => targetPattern.test(f.split("/").pop()));
+		for (const epicFile of matched) try {
 			const content = readFileSync$1(epicFile, "utf-8");
 			const keys = parseStoryKeysFromEpics(content);
 			allKeys.push(...keys);
 		} catch {}
 		allKeys = sortStoryKeys([...new Set(allKeys)]);
+	} else {
+		const epicsPath = findEpicsFile(projectRoot);
+		if (epicsPath !== void 0) try {
+			const content = readFileSync$1(epicsPath, "utf-8");
+			allKeys = parseStoryKeysFromEpics(content);
+		} catch {}
+		if (allKeys.length === 0) {
+			const epicFiles = findEpicFiles(projectRoot);
+			for (const epicFile of epicFiles) try {
+				const content = readFileSync$1(epicFile, "utf-8");
+				const keys = parseStoryKeysFromEpics(content);
+				allKeys.push(...keys);
+			} catch {}
+			allKeys = sortStoryKeys([...new Set(allKeys)]);
+		}
 	}
 	if (allKeys.length === 0) return [];
 	const existingKeys = collectExistingStoryKeys(projectRoot);
@@ -14884,7 +16125,7 @@ function mapInternalPhaseToEventPhase(internalPhase) {
 	}
 }
 async function runRunAction(options) {
-	const { pack: packName, from: startPhase, stopAfter, concept: conceptArg, conceptFile, stories: storiesArg, concurrency, outputFormat, projectRoot, events: eventsFlag, verbose: verboseFlag, tui: tuiFlag, skipUx, research: researchFlag, skipResearch: skipResearchFlag, skipPreflight, registry: injectedRegistry } = options;
+	const { pack: packName, from: startPhase, stopAfter, concept: conceptArg, conceptFile, stories: storiesArg, concurrency, outputFormat, projectRoot, events: eventsFlag, verbose: verboseFlag, tui: tuiFlag, skipUx, research: researchFlag, skipResearch: skipResearchFlag, skipPreflight, epic: epicNumber, registry: injectedRegistry } = options;
 	if (startPhase !== void 0 && !VALID_PHASES.includes(startPhase)) {
 		const errorMsg = `Invalid phase '${startPhase}'. Valid phases: ${VALID_PHASES.join(", ")}`;
 		if (outputFormat === "json") process.stdout.write(formatOutput(null, "json", false, errorMsg) + "\n");
@@ -14948,12 +16189,19 @@ async function runRunAction(options) {
 		});
 	} catch {}
 	let tokenCeilings;
+	let telemetryEnabled = false;
+	let telemetryPort = 4318;
 	try {
 		const configSystem = createConfigSystem({ projectConfigDir: dbDir });
 		await configSystem.load();
-		tokenCeilings = configSystem.getConfig().token_ceilings;
+		const cfg = configSystem.getConfig();
+		tokenCeilings = cfg.token_ceilings;
+		if (cfg.telemetry?.enabled === true) {
+			telemetryEnabled = true;
+			telemetryPort = cfg.telemetry.port ?? 4318;
+		}
 	} catch {
-		logger.debug("Config loading skipped — using default token ceilings");
+		logger.debug("Config loading skipped — using default token ceilings and telemetry settings");
 	}
 	let parsedStoryKeys = [];
 	if (storiesArg !== void 0 && storiesArg !== "") {
@@ -15008,6 +16256,7 @@ async function runRunAction(options) {
 		...researchFlag === true ? { research: true } : {},
 		...skipResearchFlag === true ? { skipResearch: true } : {},
 		...skipPreflight === true ? { skipPreflight: true } : {},
+		...epicNumber !== void 0 ? { epic: epicNumber } : {},
 		...injectedRegistry !== void 0 ? { registry: injectedRegistry } : {}
 	});
 	let storyKeys = [...parsedStoryKeys];
@@ -15056,8 +16305,11 @@ async function runRunAction(options) {
 				storyKeys = storyKeys.filter((k) => !completedStoryKeys.has(k));
 			}
 			if (storyKeys.length === 0) {
-				storyKeys = discoverPendingStoryKeys(projectRoot);
-				if (storyKeys.length > 0) process.stdout.write(`Discovered ${storyKeys.length} pending stories from epics.md: ${storyKeys.join(", ")}\n`);
+				storyKeys = discoverPendingStoryKeys(projectRoot, epicNumber);
+				if (storyKeys.length > 0) {
+					const scopeLabel = epicNumber !== void 0 ? `epic ${epicNumber}` : "epics.md";
+					process.stdout.write(`Discovered ${storyKeys.length} pending stories from ${scopeLabel}: ${storyKeys.join(", ")}\n`);
+				}
 			}
 			if (storyKeys.length === 0) {
 				if (outputFormat === "human") process.stdout.write("No pending stories found in decision store.\n");
@@ -15407,6 +16659,7 @@ async function runRunAction(options) {
 				});
 			});
 		}
+		const ingestionServer = telemetryEnabled ? new IngestionServer({ port: telemetryPort }) : void 0;
 		const orchestrator = createImplementationOrchestrator({
 			db,
 			pack,
@@ -15421,7 +16674,8 @@ async function runRunAction(options) {
 				skipPreflight: skipPreflight === true
 			},
 			projectRoot,
-			tokenCeilings
+			tokenCeilings,
+			...ingestionServer !== void 0 ? { ingestionServer } : {}
 		});
 		if (outputFormat === "human" && progressRenderer === void 0 && ndjsonEmitter === void 0) {
 			process.stdout.write(`Starting pipeline: ${storyKeys.length} story/stories, concurrency=${concurrency}\n`);
@@ -15755,7 +17009,10 @@ async function runFullPipeline(options) {
 						process.stdout.write(`  [ESCALATED] ${payload.storyKey}: ${payload.lastVerdict}\n`);
 					});
 				}
-				const storyKeys = resolveStoryKeys(db, projectRoot, { explicit: explicitStories });
+				const storyKeys = resolveStoryKeys(db, projectRoot, {
+					explicit: explicitStories,
+					epicNumber: options.epic
+				});
 				if (storyKeys.length === 0 && outputFormat === "human") process.stdout.write("[IMPLEMENTATION] No stories found. Run solutioning first or pass --stories.\n");
 				if (outputFormat === "human") process.stdout.write(`[IMPLEMENTATION] Starting ${storyKeys.length} stories with concurrency=${concurrency}\n`);
 				await orchestrator.run(storyKeys);
@@ -15819,7 +17076,7 @@ async function runFullPipeline(options) {
 	}
 }
 function registerRunCommand(program, _version = "0.0.0", projectRoot = process.cwd(), registry) {
-	program.command("run").description("Run the autonomous pipeline (use --from to start from a specific phase)").option("--pack <name>", "Methodology pack name", "bmad").option("--from <phase>", "Start from this phase: analysis, planning, solutioning, implementation").option("--stop-after <phase>", "Stop pipeline after this phase completes").option("--concept <text>", "Inline concept text (required when --from analysis)").option("--concept-file <path>", "Path to a file containing the concept text").option("--stories <keys>", "Comma-separated story keys (e.g., 10-1,10-2)").option("--concurrency <n>", "Maximum parallel conflict groups", (v) => parseInt(v, 10), 3).option("--project-root <path>", "Project root directory", projectRoot).option("--output-format <format>", "Output format: human (default) or json", "human").option("--events", "Emit structured NDJSON events on stdout for programmatic consumption").option("--verbose", "Show detailed pino log output").option("--help-agent", "Print a machine-optimized prompt fragment for AI agents and exit").option("--tui", "Show TUI dashboard").option("--skip-ux", "Skip the UX design phase even if enabled in the pack manifest").option("--research", "Enable the research phase even if not set in the pack manifest").option("--skip-research", "Skip the research phase even if enabled in the pack manifest").option("--skip-preflight", "Skip the pre-flight build check (escape hatch for known-broken projects)").action(async (opts) => {
+	program.command("run").description("Run the autonomous pipeline (use --from to start from a specific phase)").option("--pack <name>", "Methodology pack name", "bmad").option("--from <phase>", "Start from this phase: analysis, planning, solutioning, implementation").option("--stop-after <phase>", "Stop pipeline after this phase completes").option("--concept <text>", "Inline concept text (required when --from analysis)").option("--concept-file <path>", "Path to a file containing the concept text").option("--stories <keys>", "Comma-separated story keys (e.g., 10-1,10-2)").option("--epic <n>", "Scope story discovery to a single epic number (e.g., 27)", (v) => parseInt(v, 10)).option("--concurrency <n>", "Maximum parallel conflict groups", (v) => parseInt(v, 10), 3).option("--project-root <path>", "Project root directory", projectRoot).option("--output-format <format>", "Output format: human (default) or json", "human").option("--events", "Emit structured NDJSON events on stdout for programmatic consumption").option("--verbose", "Show detailed pino log output").option("--help-agent", "Print a machine-optimized prompt fragment for AI agents and exit").option("--tui", "Show TUI dashboard").option("--skip-ux", "Skip the UX design phase even if enabled in the pack manifest").option("--research", "Enable the research phase even if not set in the pack manifest").option("--skip-research", "Skip the research phase even if enabled in the pack manifest").option("--skip-preflight", "Skip the pre-flight build check (escape hatch for known-broken projects)").action(async (opts) => {
 		if (opts.helpAgent) {
 			process.exitCode = await runHelpAgent();
 			return;
@@ -15843,6 +17100,7 @@ function registerRunCommand(program, _version = "0.0.0", projectRoot = process.c
 			concept: opts.concept,
 			conceptFile: opts.conceptFile,
 			stories: opts.stories,
+			epic: opts.epic,
 			concurrency: opts.concurrency,
 			outputFormat,
 			projectRoot: opts.projectRoot,
@@ -15860,5 +17118,5 @@ function registerRunCommand(program, _version = "0.0.0", projectRoot = process.c
 }
 
 //#endregion
-export { DEFAULT_CONFIG, DEFAULT_ROUTING_POLICY, DatabaseWrapper, DoltNotInstalled, FileStateStore, SUBSTRATE_OWNED_SETTINGS_KEYS, VALID_PHASES, buildPipelineStatusOutput, checkDoltInstalled, createConfigSystem, createContextCompiler, createDispatcher, createDoltClient, createImplementationOrchestrator, createPackLoader, createPhaseOrchestrator, createStateStore, createStopAfterGate, findPackageRoot, formatOutput, formatPhaseCompletionSummary, formatPipelineStatusHuman, formatPipelineSummary, formatTokenTelemetry, getAllDescendantPids, getAutoHealthData, getSubstrateDefaultSettings, initializeDolt, parseDbTimestampAsUtc, registerHealthCommand, registerRunCommand, resolveBmadMethodSrcPath, resolveBmadMethodVersion, resolveMainRepoRoot, resolveStoryKeys, runAnalysisPhase, runMigrations, runPlanningPhase, runRunAction, runSolutioningPhase, validateStopAfterFromConflict };
-//# sourceMappingURL=run-DO9n3cwy.js.map
+export { DEFAULT_CONFIG, DEFAULT_ROUTING_POLICY, DatabaseWrapper, DoltNotInstalled, FileStateStore, SUBSTRATE_OWNED_SETTINGS_KEYS, TelemetryPersistence, VALID_PHASES, buildPipelineStatusOutput, checkDoltInstalled, createConfigSystem, createContextCompiler, createDispatcher, createDoltClient, createImplementationOrchestrator, createPackLoader, createPhaseOrchestrator, createStateStore, createStopAfterGate, findPackageRoot, formatOutput, formatPhaseCompletionSummary, formatPipelineStatusHuman, formatPipelineSummary, formatTokenTelemetry, getAllDescendantPids, getAutoHealthData, getSubstrateDefaultSettings, initializeDolt, parseDbTimestampAsUtc, registerHealthCommand, registerRunCommand, resolveBmadMethodSrcPath, resolveBmadMethodVersion, resolveMainRepoRoot, resolveStoryKeys, runAnalysisPhase, runMigrations, runPlanningPhase, runRunAction, runSolutioningPhase, validateStopAfterFromConflict };
+//# sourceMappingURL=run-Fzhz3-mv.js.map