substrate-ai 0.20.130 → 0.20.132

package/dist/adapter-registry-D70o7g1c.js

@@ -0,0 +1,4 @@
+import { AdapterRegistry } from "./dist-BUDAiEaH.js";
+import "./adapter-registry-DIcrxjH8.js";
+
+export { AdapterRegistry };

package/dist/cli/index.js

@@ -1,20 +1,20 @@
 #!/usr/bin/env node
-import { FileKvStore, SUBSTRATE_OWNED_SETTINGS_KEYS, VALID_PHASES, buildPipelineStatusOutput, createDatabaseAdapter, createDoltOperatorReader, findPackageRoot, formatOutput, formatPipelineStatusHuman, formatPipelineSummary, formatTokenTelemetry, getAllDescendantPids, getAutoHealthData, getSubstrateDefaultSettings, inspectProcessTree, parseDbTimestampAsUtc, registerHealthCommand, resolveBmadMethodSrcPath, resolveBmadMethodVersion } from "../health-C5qUaNup.js";
+import { FileKvStore, SUBSTRATE_OWNED_SETTINGS_KEYS, VALID_PHASES, buildPipelineStatusOutput, createDatabaseAdapter, createDoltOperatorReader, findPackageRoot, formatOutput, formatPipelineStatusHuman, formatPipelineSummary, formatTokenTelemetry, getAllDescendantPids, getAutoHealthData, getSubstrateDefaultSettings, inspectProcessTree, parseDbTimestampAsUtc, registerHealthCommand, resolveBmadMethodSrcPath, resolveBmadMethodVersion } from "../health-BtNrnj3J.js";
 import { createLogger } from "../logger-KeHncl-f.js";
 import { createEventBus } from "../helpers-CElYrONe.js";
-import { AdapterRegistry, BudgetConfigSchema, CURRENT_CONFIG_FORMAT_VERSION, CURRENT_TASK_GRAPH_VERSION, ConfigError, CostTrackerConfigSchema, DEFAULT_CONFIG, DoltClient, DoltNotInstalled, GlobalSettingsSchema, InMemoryDatabaseAdapter, IngestionServer, MonitorDatabaseImpl, OPERATIONAL_FINDING, PartialGlobalSettingsSchema, PartialProviderConfigSchema, ProvidersSchema, RoutingRecommender, STORY_METRICS, TelemetryConfigSchema, addTokenUsage, aggregateTokenUsageForRun, checkDoltInstalled, compareRunMetrics, createAmendmentRun, createConfigSystem, createDecision, createPipelineRun, createStderrLogger, getActiveDecisions, getAllCostEntriesFiltered, getBaselineRunMetrics, getDecisionsByCategory, getDecisionsByPhaseForRun, getLatestCompletedRun, getLatestRun, getPipelineRunById, getPlanningCostTotal, getRetryableEscalations, getRunMetrics, getRunningPipelineRuns, getSessionCostSummary, getSessionCostSummaryFiltered, getStoryMetricsForRun, getTokenUsageSummary, incrementRunRestarts, initSchema, initWorkGraphSchema, initializeDolt, listRunMetrics, loadParentRunDecisions, supersedeDecision, swallowDebug, tagRunAsBaseline, updatePipelineRun } from "../dist-Bc0-6VcX.js";
-import { AdapterTelemetryPersistence, AppError, DoltRepoMapMetaRepository, DoltSymbolRepository, ERR_REPO_MAP_STORAGE_WRITE, EpicIngester, GLOBSTAR, GitClient, GrammarLoader, Minimatch, Minipass, RepoMapInjector, RepoMapModule, RepoMapQueryEngine, RepoMapStorage, SymbolParser, createContextCompiler, createDispatcher, createEventEmitter, createGitWorktreeManager, createImplementationOrchestrator, createPackLoader, createPhaseOrchestrator, createStopAfterGate, createTelemetryAdvisor, escape, formatPhaseCompletionSummary, getFactoryRunSummaries, getScenarioResultsForRun, getTwinRunsForRun, listGraphRuns, registerExportCommand, registerFactoryCommand, registerRunCommand, registerScenariosCommand, resolveStoryKeys, runAnalysisPhase, runPlanningPhase, runProbeAuthor, runSolutioningPhase, unescape, validateStopAfterFromConflict } from "../run-jVpLtRRy.js";
+import { AdapterRegistry, BudgetConfigSchema, CURRENT_CONFIG_FORMAT_VERSION, CURRENT_TASK_GRAPH_VERSION, ConfigError, CostTrackerConfigSchema, DEFAULT_CONFIG, DoltClient, DoltNotInstalled, GlobalSettingsSchema, InMemoryDatabaseAdapter, IngestionServer, MonitorDatabaseImpl, OPERATIONAL_FINDING, PartialGlobalSettingsSchema, PartialProviderConfigSchema, ProvidersSchema, RoutingRecommender, STORY_METRICS, TelemetryConfigSchema, addTokenUsage, aggregateTokenUsageForRun, checkDoltInstalled, compareRunMetrics, createAmendmentRun, createConfigSystem, createDecision, createPipelineRun, createStderrLogger, getActiveDecisions, getAllCostEntriesFiltered, getBaselineRunMetrics, getDecisionsByCategory, getDecisionsByPhaseForRun, getLatestCompletedRun, getLatestRun, getPipelineRunById, getPlanningCostTotal, getRetryableEscalations, getRunMetrics, getRunningPipelineRuns, getSessionCostSummary, getSessionCostSummaryFiltered, getStoryMetricsForRun, getTokenUsageSummary, incrementRunRestarts, initSchema, initWorkGraphSchema, initializeDolt, listRunMetrics, loadParentRunDecisions, supersedeDecision, swallowDebug, tagRunAsBaseline, updatePipelineRun } from "../dist-BUDAiEaH.js";
+import { AdapterTelemetryPersistence, AppError, DoltRepoMapMetaRepository, DoltSymbolRepository, ERR_REPO_MAP_STORAGE_WRITE, EpicIngester, GLOBSTAR, GitClient, GrammarLoader, Minimatch, Minipass, RepoMapInjector, RepoMapModule, RepoMapQueryEngine, RepoMapStorage, SymbolParser, createContextCompiler, createDispatcher, createEventEmitter, createGitWorktreeManager, createImplementationOrchestrator, createPackLoader, createPhaseOrchestrator, createStopAfterGate, createTelemetryAdvisor, escape, formatPhaseCompletionSummary, getFactoryRunSummaries, getScenarioResultsForRun, getTwinRunsForRun, listGraphRuns, registerExportCommand, registerFactoryCommand, registerRunCommand, registerScenariosCommand, resolveStoryKeys, runAnalysisPhase, runPlanningPhase, runProbeAuthor, runSolutioningPhase, unescape, validateStopAfterFromConflict } from "../run-DAb4BgAO.js";
 import "../adapter-registry-DIcrxjH8.js";
-import { RunManifest, SupervisorLock, ZERO_FINDINGS_BY_AUTHOR, ZERO_FINDING_COUNTS, ZERO_PROBE_AUTHOR_METRICS, aggregateProbeAuthorMetrics, parseRuntimeProbes, readCurrentRunId, resolveMainRepoRoot, resolveRunManifest, rollupFindingCounts, rollupFindingsByAuthor, rollupProbeAuthorByClass, rollupProbeAuthorMetrics, runAcTraceabilityCheck } from "../manifest-read-D_HmoOcb.js";
-import "../errors-CwQM_6Yk.js";
+import { RunManifest, SupervisorLock, ZERO_FINDINGS_BY_AUTHOR, ZERO_FINDING_COUNTS, ZERO_PROBE_AUTHOR_METRICS, aggregateProbeAuthorMetrics, parseRuntimeProbes, readCurrentRunId, resolveMainRepoRoot, resolveRunManifest, rollupFindingCounts, rollupFindingsByAuthor, rollupProbeAuthorByClass, rollupProbeAuthorMetrics, runAcTraceabilityCheck } from "../manifest-read-CKmTZKA5.js";
+import "../errors-pJaYVCUJ.js";
 import "../routing-DFxoKHDt.js";
 import { WorkGraphRepository } from "../work-graph-repository-DZyJv5pV.js";
 import "../decisions-CzSIEeGP.js";
 import "../decision-router-DblHY8se.js";
-import "../interactive-prompt-y6udulxR.js";
+import "../interactive-prompt-DKNFNQ7u.js";
 import "../recovery-engine-BKGBeBnW.js";
 import "../version-manager-impl-qFBiO4Eh.js";
-import { registerUpgradeCommand } from "../upgrade-BlBDCOfS.js";
+import { registerUpgradeCommand } from "../upgrade-BApZ1sPK.js";
 import { Command } from "commander";
 import { fileURLToPath } from "url";
 import { dirname, join, resolve } from "path";
@@ -30,7 +30,7 @@ import { randomUUID } from "node:crypto";
 import { z } from "zod";
 import * as fs from "node:fs/promises";
 import { lstat, readFile as readFile$1, readdir as readdir$1, readlink, realpath } from "node:fs/promises";
-import { appendFileSync, chmodSync, cpSync, existsSync as existsSync$1, lstatSync, mkdirSync as mkdirSync$1, readFileSync as readFileSync$1, readdir as readdir$2, readdirSync as readdirSync$1, readlinkSync, realpathSync as realpathSync$1, rmSync as rmSync$1, statSync as statSync$1, unlinkSync as unlinkSync$1, writeFileSync as writeFileSync$1 } from "fs";
+import { chmodSync, cpSync, existsSync as existsSync$1, lstatSync, mkdirSync as mkdirSync$1, readFileSync as readFileSync$1, readdir as readdir$2, readdirSync as readdirSync$1, readlinkSync, realpathSync as realpathSync$1, rmSync as rmSync$1, statSync as statSync$1, unlinkSync as unlinkSync$1, writeFileSync as writeFileSync$1 } from "fs";
 import { homedir } from "os";
 import { createRequire } from "node:module";
 import { fileURLToPath as fileURLToPath$1 } from "node:url";
@@ -516,6 +516,53 @@ const DEFAULT_ROUTING_POLICY = {
 	]
 };
 
+//#endregion
+//#region src/modules/config/derive-routing-policy.ts
+/**
+* Returns a copy of `basePolicy` filtered to the providers enabled in
+* `providers`. Provider preference order is taken from `basePolicy` (the
+* order each provider first appears as default/preferred/fallback), so output
+* is deterministic regardless of the `providers` object key order.
+*
+* Edge case: if no providers are enabled (e.g. the no-selection init fallback
+* where every provider defaults to `enabled: false`), the base policy is
+* returned unchanged — there is nothing to derive from, and an empty policy
+* would be invalid.
+*/
+function deriveRoutingPolicy(basePolicy, providers) {
+	const enabled = Object.entries(providers).filter(([, cfg]) => cfg?.enabled === true).map(([key]) => key);
+	if (enabled.length === 0) return structuredClone(basePolicy);
+	const ranking = [];
+	const addRank = (p) => {
+		if (!ranking.includes(p)) ranking.push(p);
+	};
+	addRank(basePolicy.default_provider);
+	for (const rule of basePolicy.rules) {
+		addRank(rule.preferred_provider);
+		rule.fallback_providers.forEach(addRank);
+	}
+	const rankOf = (p) => {
+		const i = ranking.indexOf(p);
+		return i === -1 ? Number.MAX_SAFE_INTEGER : i;
+	};
+	const enabledRanked = [...enabled].sort((a, b) => rankOf(a) - rankOf(b));
+	const isEnabled = (p) => enabled.includes(p);
+	const defaultProvider = isEnabled(basePolicy.default_provider) ? basePolicy.default_provider : enabledRanked[0];
+	const rules = basePolicy.rules.map((rule) => {
+		const ordered = [rule.preferred_provider, ...rule.fallback_providers].filter(isEnabled);
+		for (const p of enabledRanked) if (!ordered.includes(p)) ordered.push(p);
+		return {
+			task_type: rule.task_type,
+			preferred_provider: ordered[0] ?? rule.preferred_provider,
+			fallback_providers: ordered.slice(1)
+		};
+	});
+	return {
+		default_provider: defaultProvider,
+		rules
+	};
+}
+
 //#endregion
 //#region src/modules/config/config-schema.ts
 const RoutingRuleSchema = z.object({
@@ -562,7 +609,8 @@ const SubstrateConfigSchema = z.object({
 	telemetry: TelemetryConfigSchema.optional(),
 	default_agent: z.string().optional(),
 	supervisor_poll_interval_seconds: z.number().int().positive().optional(),
-	retry_budget: z.number().int().positive().optional()
+	retry_budget: z.number().int().positive().optional(),
+	epics_path: z.string().optional()
 }).strict();
 const PartialSubstrateConfigSchema = z.object({
 	config_format_version: z.enum(["1"]).optional(),
@@ -580,9 +628,63 @@ const PartialSubstrateConfigSchema = z.object({
 	telemetry: TelemetryConfigSchema.partial().optional(),
 	default_agent: z.string().optional(),
 	supervisor_poll_interval_seconds: z.number().int().positive().optional(),
-	retry_budget: z.number().int().positive().optional()
+	retry_budget: z.number().int().positive().optional(),
+	epics_path: z.string().optional()
 }).strict();
 
+//#endregion
+//#region src/cli/commands/substrate-gitignore.ts
+/**
+* Compute the `.gitignore` content substrate should write so that everything
+* under `.substrate/` is ignored EXCEPT the operator-shared `config.yaml`,
+* consistent with the AGENTS.md/CLAUDE.md/GEMINI.md guidance.
+*
+* The previous init writer enumerated individual runtime files, which both
+* (a) diverged from the documented negation pattern and (b) left a pre-existing
+* wholesale `.substrate/` dir-ignore in place. A dir-ignore (`.substrate/` or
+* `.substrate`) makes git skip the directory entirely, so `!.substrate/config.yaml`
+* can NEVER re-include the file — the fix MUST convert it to `.substrate/*`
+* (ignore the contents, not the directory) before the negation can work.
+*
+* Pure + exported for unit testing; init.ts is the only caller.
+*/
+/** Wholesale `.substrate` dir-ignore forms that block `!config.yaml` re-inclusion. */
+const WHOLESALE_SUBSTRATE_IGNORES = new Set([
+	".substrate",
+	".substrate/",
+	"/.substrate",
+	"/.substrate/"
+]);
+const STAR = ".substrate/*";
+const CONFIG_NEGATION = "!.substrate/config.yaml";
+const CODEX_PROMPTS = ".codex/prompts/";
+const CODEX_SKILLS = ".codex/skills/";
+/**
+* Returns the updated `.gitignore` content. Idempotent: running it on its own
+* output returns `changed: false`.
+*/
+function computeSubstrateGitignore(existing) {
+	const lines = existing.split("\n").map((line) => WHOLESALE_SUBSTRATE_IGNORES.has(line.trim()) ? STAR : line);
+	const trimmed = lines.map((l) => l.trim());
+	const append = [];
+	if (!trimmed.includes(STAR)) append.push(STAR);
+	const starIdx = trimmed.lastIndexOf(STAR);
+	const negIdx = trimmed.lastIndexOf(CONFIG_NEGATION);
+	const negationEffective = negIdx !== -1 && negIdx > starIdx;
+	if (!negationEffective) append.push(CONFIG_NEGATION);
+	if (!trimmed.includes(CODEX_PROMPTS)) append.push(CODEX_PROMPTS);
+	if (!trimmed.includes(CODEX_SKILLS)) append.push(CODEX_SKILLS);
+	let content = lines.join("\n");
+	if (append.length > 0) {
+		const needsNewline = content.length > 0 && !content.endsWith("\n");
+		content += (needsNewline ? "\n" : "") + "\n# Substrate state — track only the operator config\n" + append.join("\n") + "\n";
+	}
+	return {
+		content,
+		changed: content !== existing
+	};
+}
+
 //#endregion
 //#region src/modules/project-profile/detect.ts
 function execFileAsync(cmd, args, opts) {
@@ -1738,6 +1840,7 @@ function syncCommandsAsPrompts(commandsDir, promptsDir, ownershipPrefixes, nameP
 *
 * Returns the number of skill directories copied.
 */
+/** Exported for testing. */
 function syncSkillsToTarget(srcSkillsDir, destSkillsDir, ownershipPrefixes, namePrefix) {
 	if (!existsSync$1(srcSkillsDir)) return 0;
 	mkdirSync$1(destSkillsDir, { recursive: true });
@@ -1764,12 +1867,20 @@ function syncSkillsToTarget(srcSkillsDir, destSkillsDir, ownershipPrefixes, name
 	for (const entry of sourceEntries) {
 		const destName = namePrefix && !entry.name.startsWith(namePrefix) ? `${namePrefix}${entry.name}` : entry.name;
 		const dest = join(destSkillsDir, destName);
-		rmSync$1(dest, {
-			recursive: true,
-			force: true
-		});
-		cpSync(join(srcSkillsDir, entry.name), dest, { recursive: true });
-		count++;
+		try {
+			rmSync$1(dest, {
+				recursive: true,
+				force: true
+			});
+			cpSync(join(srcSkillsDir, entry.name), dest, { recursive: true });
+			count++;
+		} catch (err) {
+			logger$18.warn({
+				skill: entry.name,
+				dest,
+				err: err instanceof Error ? err.message : String(err)
+			}, "Skipped skill due to copy error; continuing with the rest");
+		}
 	}
 	return count;
 }
@@ -1856,13 +1967,14 @@ const PROVIDER_KEY_ENV = {
 	codex: "OPENAI_API_KEY",
 	gemini: "GOOGLE_API_KEY"
 };
+/** Exported for testing. */
 function buildProviderConfig(adapterId, cliPath, subscriptionRouting) {
 	const providerKey = ADAPTER_TO_PROVIDER[adapterId] ?? adapterId;
 	const defaults = PROVIDER_DEFAULTS[providerKey];
 	if (!defaults) throw new ConfigError(`Unknown provider: ${providerKey}`, { adapterId });
 	return {
 		...defaults,
-		enabled: true,
+		enabled: subscriptionRouting !== "disabled",
 		cli_path: cliPath,
 		subscription_routing: subscriptionRouting
 	};
@@ -1993,12 +2105,18 @@ async function runInitAction(options) {
 			providers: configProviders,
 			telemetry: DEFAULT_CONFIG.telemetry
 		};
-		const routingPolicy = structuredClone(DEFAULT_ROUTING_POLICY);
+		const routingPolicy = deriveRoutingPolicy(DEFAULT_ROUTING_POLICY, configProviders);
 		await mkdir(substrateDir, { recursive: true });
 		const configHeader = "# Substrate Configuration\n# Generated by `substrate init`\n# Edit this file to customize your AI agent orchestration settings.\n# API keys must be set as environment variables — never stored here.\n#\n# Provider API key env vars:\n" + Object.entries(PROVIDER_KEY_ENV).map(([p, env]) => `#   ${p}: ${env}`).join("\n") + "\n\n";
-		await writeFile(configPath, configHeader + yaml.dump(config), "utf-8");
+		const configExists = existsSync$1(configPath);
+		if (configExists && !force) {
+			if (outputFormat !== "json") process.stdout.write("  .substrate/config.yaml already exists — preserving (use --force to overwrite)\n");
+		} else await writeFile(configPath, configHeader + yaml.dump(config), "utf-8");
 		const routingHeader = "# Substrate Routing Policy\n# Defines how tasks are routed to AI providers.\n# Customize rules to match your workflow and available agents.\n\n";
-		await writeFile(routingPolicyPath, routingHeader + yaml.dump(routingPolicy), "utf-8");
+		const routingExists = existsSync$1(routingPolicyPath);
+		if (routingExists && !force) {
+			if (outputFormat !== "json") process.stdout.write("  .substrate/routing-policy.yaml already exists — preserving (use --force to overwrite)\n");
+		} else await writeFile(routingPolicyPath, routingHeader + yaml.dump(routingPolicy), "utf-8");
 		const projectProfilePath = join(substrateDir, "project-profile.yaml");
 		let detectedProfile = null;
 		let projectProfileWritten = false;
@@ -2080,27 +2198,12 @@ async function runInitAction(options) {
 			else if (outputFormat !== "json") process.stderr.write("Warning: --install-user-scope requested but HOME/USERPROFILE is not set\n");
 		}
 		const gitignorePath = join(projectRoot, ".gitignore");
-		const runtimeEntries = [
-			".substrate/orchestrator.pid",
-			".substrate/current-run-id",
-			".substrate/scenarios/",
-			".substrate/state/",
-			".substrate/runs/",
-			".substrate/notifications/",
-			".substrate/kv-metrics.json",
-			".substrate/latest-heartbeat-per-story-state.json",
-			".substrate/substrate.db",
-			".substrate/substrate.db-journal",
-			".codex/prompts/",
-			".codex/skills/"
-		];
 		try {
 			const existing = existsSync$1(gitignorePath) ? readFileSync$1(gitignorePath, "utf-8") : "";
-			const missing = runtimeEntries.filter((e) => !existing.includes(e));
-			if (missing.length > 0) {
-				const block = "\n# Substrate runtime files\n" + missing.join("\n") + "\n";
-				appendFileSync(gitignorePath, block);
-				logger$18.info({ entries: missing }, "Added substrate runtime files to .gitignore");
+			const { content, changed } = computeSubstrateGitignore(existing);
+			if (changed) {
+				writeFileSync$1(gitignorePath, content);
+				logger$18.info("Updated .gitignore: track only .substrate/config.yaml");
 			}
 		} catch (err) {
 			logger$18.debug({ err }, "Could not update .gitignore (non-fatal)");
@@ -6890,7 +6993,7 @@ async function runStatusAction(options) {
 			logger$15.debug({ err }, "Work graph query failed, continuing without work graph data");
 		}
 		if (run === void 0) {
-			const { inspectProcessTree: inspectProcessTree$1 } = await import("../health-AQjZv_aT.js");
+			const { inspectProcessTree: inspectProcessTree$1 } = await import("../health-Cb4jPuRd.js");
 			const substrateDirPath = join(projectRoot, ".substrate");
 			const processInfo = inspectProcessTree$1({
 				projectRoot,
@@ -7838,7 +7941,7 @@ function defaultSupervisorDeps() {
 				if (cached === null) {
 					const { AdapterRegistry: AR } = await import(
 						/* @vite-ignore */
-						"../adapter-registry-B9G8dfn-.js"
+						"../adapter-registry-D70o7g1c.js"
 );
 					cached = new AR();
 					await cached.discoverAndRegister();
@@ -8405,11 +8508,11 @@ async function runSupervisorAction(options, deps = {}) {
 						try {
 							const { createExperimenter } = await import(
 								/* @vite-ignore */
-								"../experimenter-D9yPAcRD.js"
+								"../experimenter-CpnxTV5m.js"
 );
 							const { getLatestRun: getLatest } = await import(
 								/* @vite-ignore */
-								"../decisions-B4A60aRy.js"
+								"../decisions-DAuvU4q9.js"
 );
 							const expAdapter = createDatabaseAdapter({
 								backend: "auto",
@@ -8419,7 +8522,7 @@ async function runSupervisorAction(options, deps = {}) {
 								await initSchema(expAdapter);
 								const { runRunAction: runPipeline } = await import(
 									/* @vite-ignore */
-									"../run-BsPkkWob.js"
+									"../run-BMx6kY0E.js"
 );
 								const runStoryFn = async (opts) => {
 									const exitCode = await runPipeline({
@@ -8944,7 +9047,7 @@ async function runMetricsAction(options) {
 			const routingConfigPath = join(dbDir, "routing.yml");
 			let routingConfig = null;
 			if (existsSync$1(routingConfigPath)) try {
-				const { loadModelRoutingConfig } = await import("../routing-DFwoxEpT.js");
+				const { loadModelRoutingConfig } = await import("../routing-CEd36PVz.js");
 				routingConfig = loadModelRoutingConfig(routingConfigPath);
 			} catch {}
 			if (routingConfig === null) routingConfig = {
@@ -11904,7 +12007,11 @@ var EpicParser = class {
 	*/
 	parseStories(content) {
 		const headingMatch = STORY_MAP_HEADING_RE.exec(content);
-		if (!headingMatch) throw new Error("No story map section found in document");
+		if (!headingMatch) {
+			const hasPerStoryHeadings = /^#{2,4}\s+Story\s+\d+[-._]\d+/im.test(content);
+			const hint = hasPerStoryHeadings ? "\n\nThis document already has per-story headings (e.g. `### Story 7-7:` / `#### Story 7.7:`), which `substrate run --stories <key>` consumes directly — ingest-epic is not required to dispatch from it." : "";
+			throw new Error("No story map section found in document. ingest-epic expects a heading containing \"Story Map\" followed by sprint blocks (`**Sprint N — Label:**`) and story lines (`- N-M: Title (P0, Medium)`)." + hint);
+		}
 		const afterHeading = content.slice(headingMatch.index + headingMatch[0].length);
 		const stories = [];
 		let currentSprint = 0;
@@ -12733,13 +12840,24 @@ function wallClockMs(state) {
 	const end = new Date(state.completed_at).getTime();
 	return isNaN(start) || isNaN(end) ? void 0 : end - start;
 }
+/**
+* Compute the run verdict. Must honor the manifest's `run_status`, not only the
+* per-story counts: a run that failed before dispatching any story has empty
+* scope (total=0), and a counts-only verdict would vacuously report "ALL PASSED"
+* for a failed run. Exported for testing.
+*/
+function computeReportVerdict(summary, runStatus) {
+	if (summary.escalated > 0 || summary.failed > 0 || runStatus === "failed") return "NEEDS ATTENTION";
+	if (summary.total === 0) return "NO STORIES RUN";
+	return "ALL PASSED";
+}
 function renderHuman(output, manifest) {
 	const lines = [];
 	const { runId, summary, stories, escalations, cost, duration, halts } = output;
 	const durationStr = duration.wall_clock_ms != null ? formatDurationMs(duration.wall_clock_ms) : "unknown";
 	const costStr = `$${cost.spent.toFixed(4)}`;
 	const ceilingStr = cost.ceiling != null ? ` / $${cost.ceiling.toFixed(4)} ceiling (${cost.utilization ?? "?"}) ${cost.overCeiling ? "[OVER CEILING]" : ""}` : "";
-	const verdict = summary.escalated > 0 || summary.failed > 0 ? "NEEDS ATTENTION" : "ALL PASSED";
+	const verdict = computeReportVerdict(summary, manifest.run_status);
 	lines.push(`══════════════════════════════════════════════════════════`);
 	lines.push(`  Run: ${runId}`);
 	lines.push(`  Duration: ${durationStr}`);
@@ -12747,6 +12865,10 @@ function renderHuman(output, manifest) {
 	lines.push(`  Verdict: ${verdict}`);
 	lines.push(`══════════════════════════════════════════════════════════`);
 	lines.push("");
+	if (manifest.run_status === "failed" && summary.total === 0) {
+		lines.push("  ⚠ Run failed before any story was dispatched (run_status: failed, empty scope). Check the run manifest and prior output for the cause (e.g. worktree/setup error).");
+		lines.push("");
+	}
 	lines.push(`${summary.verified} verified, ${summary.recovered} recovered, ${summary.escalated} escalated, ${summary.failed} failed of ${summary.total} total`);
 	lines.push("");
 	const COL_WIDTHS = [
@@ -13235,8 +13357,8 @@ async function createProgram() {
 /** Fire-and-forget startup version check (story 8.3, AC3/AC5) */
 function checkForUpdatesInBackground(currentVersion) {
 	if (process.env.SUBSTRATE_NO_UPDATE_CHECK === "1") return;
-	import("../upgrade-OE6hMPMW.js").then(async () => {
-		const { createVersionManager } = await import("../version-manager-impl-BRVBwdma.js");
+	import("../upgrade-D4Dj7rjQ.js").then(async () => {
+		const { createVersionManager } = await import("../version-manager-impl-Bi05jQ9s.js");
 		const vm = createVersionManager();
 		const result = await vm.checkForUpdates();
 		if (result.updateAvailable) {

package/dist/{decisions-B4A60aRy.js → decisions-DAuvU4q9.js}

@@ -1,4 +1,4 @@
-import { addTokenUsage, createDecision, createPipelineRun, createRequirement, getArtifactByTypeForRun, getArtifactsByRun, getDecisionsByCategory, getDecisionsByPhase, getDecisionsByPhaseForRun, getLatestRun, getPipelineRunById, getRunningPipelineRuns, getTokenUsageSummary, listRequirements, registerArtifact, updateDecision, updatePipelineRun, updatePipelineRunConfig, upsertDecision } from "./dist-Bc0-6VcX.js";
+import { addTokenUsage, createDecision, createPipelineRun, createRequirement, getArtifactByTypeForRun, getArtifactsByRun, getDecisionsByCategory, getDecisionsByPhase, getDecisionsByPhaseForRun, getLatestRun, getPipelineRunById, getRunningPipelineRuns, getTokenUsageSummary, listRequirements, registerArtifact, updateDecision, updatePipelineRun, updatePipelineRunConfig, upsertDecision } from "./dist-BUDAiEaH.js";
 import "./decisions-CzSIEeGP.js";
 
 export { getLatestRun };

package/dist/{dist-Bc0-6VcX.js → dist-BUDAiEaH.js}

@@ -9716,6 +9716,29 @@ function stripCodeFences$1(raw) {
 /** Codex default billing modes — subscription via `codex login`, or API key */
 const CODEX_BILLING_MODES = ["subscription", "api"];
 /**
+* Signatures emitted by `codex exec` when its sandbox/approval policy prevents
+* a file write or command in non-interactive mode. The first two are the
+* "exec can't service an approval" failures; the third is what an org policy
+* prints when it overrides the requested approval/sandbox configuration.
+*/
+const CODEX_SANDBOX_BLOCK_SIGNATURES = [
+	"approval is not supported in exec mode",
+	"command execution approval is not supported",
+	"file change approval is not supported",
+	"disallowed by requirements"
+];
+/** Human-readable explanation appended to escalations caused by a Codex write-block. */
+const CODEX_SANDBOX_BLOCK_HINT = "Likely cause: Codex could not write files. Substrate runs `codex exec --sandbox workspace-write --ask-for-approval never` (normal automation mode — not the org-blocked `--dangerously-bypass-approvals-and-sandbox`). If the run log shows \"disallowed by requirements\", your org policy forbids the `never` approval policy, so Codex cannot write non-interactively on this machine — an org constraint, not substrate. Workaround: dispatch with a provider that can write here (e.g. `--agent claude-code`), or have the Codex policy permit non-interactive workspace writes.";
+/**
+* Returns the Codex-write-block hint if `output` contains a sandbox/approval
+* block signature, else null. Pure + exported for diagnostics and testing.
+*/
+function detectCodexSandboxBlock(output) {
+	if (output === void 0 || output === null || output === "") return null;
+	const lower = output.toLowerCase();
+	return CODEX_SANDBOX_BLOCK_SIGNATURES.some((sig) => lower.includes(sig)) ? CODEX_SANDBOX_BLOCK_HINT : null;
+}
+/**
 * Adapter for the OpenAI Codex CLI agent.
 *
 * Codex CLI uses stdin for the prompt and outputs JSON when --json flag is used.
@@ -9761,12 +9784,28 @@ var CodexCLIAdapter = class {
 	* Build spawn command for a coding task.
 	* Uses: `codex exec` with prompt delivered via stdin.
 	*
+	* `--sandbox workspace-write --ask-for-approval never` is required so the
+	* non-interactive `codex exec` can actually write files. Without flags, exec
+	* defaults to a read-only sandbox + an approval policy that escalates to the
+	* user — but exec has no one to approve, so file writes fail with
+	* "file change approval is not supported in exec mode" (→ create-story-no-file).
+	* `never` is exactly what Codex's own docs recommend for non-interactive runs,
+	* and this is normal automation mode — NOT the
+	* `--dangerously-bypass-approvals-and-sandbox` flag (which some org policies
+	* forbid). The planning command stays read-only (it must not write).
+	*
 	* Do NOT use --json: it produces a JSONL event stream that prevents
 	* extractYamlBlock from finding the structured result block in stdout.
 	* Raw text output is required (same rationale as Claude adapter).
 	*/
 	buildCommand(prompt, options) {
-		const args = ["exec"];
+		const args = [
+			"exec",
+			"--sandbox",
+			"workspace-write",
+			"--ask-for-approval",
+			"never"
+		];
 		if (options.additionalFlags && options.additionalFlags.length > 0) args.push(...options.additionalFlags);
 		const envEntries = {};
 		if (options.apiKey) envEntries.OPENAI_API_KEY = options.apiKey;
@@ -11279,5 +11318,5 @@ async function callLLM(params) {
 }
 
 //#endregion
-export { ADVISORY_NOTES, AdapterRegistry, AdtError, BudgetConfigSchema, CURRENT_CONFIG_FORMAT_VERSION, CURRENT_TASK_GRAPH_VERSION, Categorizer, ClaudeCodeAdapter, CodexCLIAdapter, ConfigError, ConfigIncompatibleFormatError, ConsumerAnalyzer, CostTrackerConfigSchema, DEFAULT_CONFIG, DEFAULT_GLOBAL_SETTINGS, DispatcherImpl, DoltClient, DoltNotInstalled, DoltQueryError, ESCALATION_DIAGNOSIS, EXPERIMENT_RESULT, EfficiencyScorer, GeminiCLIAdapter, GlobalSettingsSchema, InMemoryDatabaseAdapter, IngestionServer, LEARNING_FINDING, LogTurnAnalyzer, ModelRoutingConfigSchema, MonitorDatabaseImpl, OPERATIONAL_FINDING, PartialGlobalSettingsSchema, PartialProviderConfigSchema, ProviderPolicySchema, ProvidersSchema, Recommender, RoutingConfigError, RoutingRecommender, RoutingResolver, RoutingTelemetry, RoutingTokenAccumulator, RoutingTuner, STORY_METRICS, STORY_OUTCOME, SubstrateConfigSchema, TASK_TYPE_PHASE_MAP, TEST_EXPANSION_FINDING, TEST_PLAN, TelemetryConfigSchema, TelemetryNormalizer, TelemetryPipeline, TurnAnalyzer, VersionManagerImpl, addTokenUsage, aggregateTokenUsageForRun, aggregateTokenUsageForStory, buildAuditLogEntry, buildBranchName, buildModificationDirective, buildPRBody, buildWorktreePath, callLLM, checkDoltInstalled, classifyVersionGap, compareRunMetrics, createAmendmentRun, createConfigSystem, createDatabaseAdapter as createDatabaseAdapter$1, createDecision, createExperimenter, createPipelineRun, createRequirement, createStderrLogger, createVersionManager, detectInterfaceChanges, determineVerdict, getActiveDecisions, getAllCostEntriesFiltered, getArtifactByTypeForRun, getArtifactsByRun, getBaselineRunMetrics, getDecisionsByCategory, getDecisionsByPhase, getDecisionsByPhaseForRun, getLatestCompletedRun, getLatestRun, getModelTier, getPipelineRunById, getPlanningCostTotal, getRetryableEscalations, getRunMetrics, getRunningPipelineRuns, getSessionCostSummary, getSessionCostSummaryFiltered, getStoryMetricsForRun, getTokenUsageSummary, incrementRunRestarts, initSchema, initWorkGraphSchema, initializeDolt, listRequirements, listRunMetrics, loadModelRoutingConfig, loadParentRunDecisions, registerArtifact, resolvePromptFile, supersedeDecision, swallowDebug, tagRunAsBaseline, updateDecision, updatePipelineRun, updatePipelineRunConfig, upsertDecision, writeRunMetrics, writeStoryMetrics };
-//# sourceMappingURL=dist-Bc0-6VcX.js.map
+export { ADVISORY_NOTES, AdapterRegistry, AdtError, BudgetConfigSchema, CODEX_SANDBOX_BLOCK_HINT, CURRENT_CONFIG_FORMAT_VERSION, CURRENT_TASK_GRAPH_VERSION, Categorizer, ClaudeCodeAdapter, CodexCLIAdapter, ConfigError, ConfigIncompatibleFormatError, ConsumerAnalyzer, CostTrackerConfigSchema, DEFAULT_CONFIG, DEFAULT_GLOBAL_SETTINGS, DispatcherImpl, DoltClient, DoltNotInstalled, DoltQueryError, ESCALATION_DIAGNOSIS, EXPERIMENT_RESULT, EfficiencyScorer, GeminiCLIAdapter, GlobalSettingsSchema, InMemoryDatabaseAdapter, IngestionServer, LEARNING_FINDING, LogTurnAnalyzer, ModelRoutingConfigSchema, MonitorDatabaseImpl, OPERATIONAL_FINDING, PartialGlobalSettingsSchema, PartialProviderConfigSchema, ProviderPolicySchema, ProvidersSchema, Recommender, RoutingConfigError, RoutingRecommender, RoutingResolver, RoutingTelemetry, RoutingTokenAccumulator, RoutingTuner, STORY_METRICS, STORY_OUTCOME, SubstrateConfigSchema, TASK_TYPE_PHASE_MAP, TEST_EXPANSION_FINDING, TEST_PLAN, TelemetryConfigSchema, TelemetryNormalizer, TelemetryPipeline, TurnAnalyzer, VersionManagerImpl, addTokenUsage, aggregateTokenUsageForRun, aggregateTokenUsageForStory, buildAuditLogEntry, buildBranchName, buildModificationDirective, buildPRBody, buildWorktreePath, callLLM, checkDoltInstalled, classifyVersionGap, compareRunMetrics, createAmendmentRun, createConfigSystem, createDatabaseAdapter as createDatabaseAdapter$1, createDecision, createExperimenter, createPipelineRun, createRequirement, createStderrLogger, createVersionManager, detectCodexSandboxBlock, detectInterfaceChanges, determineVerdict, getActiveDecisions, getAllCostEntriesFiltered, getArtifactByTypeForRun, getArtifactsByRun, getBaselineRunMetrics, getDecisionsByCategory, getDecisionsByPhase, getDecisionsByPhaseForRun, getLatestCompletedRun, getLatestRun, getModelTier, getPipelineRunById, getPlanningCostTotal, getRetryableEscalations, getRunMetrics, getRunningPipelineRuns, getSessionCostSummary, getSessionCostSummaryFiltered, getStoryMetricsForRun, getTokenUsageSummary, incrementRunRestarts, initSchema, initWorkGraphSchema, initializeDolt, listRequirements, listRunMetrics, loadModelRoutingConfig, loadParentRunDecisions, registerArtifact, resolvePromptFile, supersedeDecision, swallowDebug, tagRunAsBaseline, updateDecision, updatePipelineRun, updatePipelineRunConfig, upsertDecision, writeRunMetrics, writeStoryMetrics };
+//# sourceMappingURL=dist-BUDAiEaH.js.map

package/dist/{errors-CwQM_6Yk.js → errors-pJaYVCUJ.js}

@@ -1,4 +1,4 @@
-import { AdtError } from "./dist-Bc0-6VcX.js";
+import { AdtError } from "./dist-BUDAiEaH.js";
 
 //#region src/core/errors.ts
 /** Error thrown when task configuration is invalid */
@@ -71,4 +71,4 @@ var TaskGraphIncompatibleFormatError = class extends AdtError {
 
 //#endregion
 export { BudgetExceededError, GitError, RecoveryError, TaskConfigError, TaskGraphCycleError, TaskGraphError, TaskGraphIncompatibleFormatError, WorkerError, WorkerNotFoundError };
-//# sourceMappingURL=errors-CwQM_6Yk.js.map
+//# sourceMappingURL=errors-pJaYVCUJ.js.map

package/dist/{experimenter-D9yPAcRD.js → experimenter-CpnxTV5m.js}

@@ -1,3 +1,3 @@
-import { buildAuditLogEntry, buildBranchName, buildModificationDirective, buildPRBody, buildWorktreePath, createExperimenter, determineVerdict, resolvePromptFile } from "./dist-Bc0-6VcX.js";
+import { buildAuditLogEntry, buildBranchName, buildModificationDirective, buildPRBody, buildWorktreePath, createExperimenter, determineVerdict, resolvePromptFile } from "./dist-BUDAiEaH.js";
 
 export { createExperimenter };

package/dist/{health-C5qUaNup.js → health-BtNrnj3J.js}

@@ -1,6 +1,6 @@
 import { createLogger } from "./logger-KeHncl-f.js";
-import { DoltClient, DoltQueryError, createDatabaseAdapter$1 as createDatabaseAdapter, getLatestRun, getPipelineRunById, initSchema } from "./dist-Bc0-6VcX.js";
-import { resolveMainRepoRoot, resolveRunManifest } from "./manifest-read-D_HmoOcb.js";
+import { DoltClient, DoltQueryError, createDatabaseAdapter$1 as createDatabaseAdapter, getLatestRun, getPipelineRunById, initSchema } from "./dist-BUDAiEaH.js";
+import { resolveMainRepoRoot, resolveRunManifest } from "./manifest-read-CKmTZKA5.js";
 import { createRequire } from "module";
 import { dirname, join } from "path";
 import { existsSync, readFileSync } from "node:fs";
@@ -1000,4 +1000,4 @@ function registerHealthCommand(program, _version = "0.0.0", projectRoot = proces
 
 //#endregion
 export { BMAD_BASELINE_TOKENS_FULL, DEFAULT_STALL_THRESHOLD_SECONDS, FileKvStore, STOP_AFTER_VALID_PHASES, STORY_KEY_PATTERN, SUBSTRATE_OWNED_SETTINGS_KEYS, VALID_PHASES, __commonJS, __require, __toESM, buildPipelineStatusOutput, createDatabaseAdapter$1 as createDatabaseAdapter, createDoltOperatorReader, findPackageRoot, formatOutput, formatPipelineStatusHuman, formatPipelineSummary, formatTokenTelemetry, getAllDescendantPids, getAutoHealthData, getSubstrateDefaultSettings, inspectProcessTree, isOrchestratorProcessLine, parseDbTimestampAsUtc, registerHealthCommand, resolveBmadMethodSrcPath, resolveBmadMethodVersion, runHealthAction, validateStoryKey };
-//# sourceMappingURL=health-C5qUaNup.js.map
+//# sourceMappingURL=health-BtNrnj3J.js.map

package/dist/{health-AQjZv_aT.js → health-Cb4jPuRd.js}

@@ -1,7 +1,7 @@
-import { DEFAULT_STALL_THRESHOLD_SECONDS, getAllDescendantPids, getAutoHealthData, inspectProcessTree, isOrchestratorProcessLine, registerHealthCommand, runHealthAction } from "./health-C5qUaNup.js";
+import { DEFAULT_STALL_THRESHOLD_SECONDS, getAllDescendantPids, getAutoHealthData, inspectProcessTree, isOrchestratorProcessLine, registerHealthCommand, runHealthAction } from "./health-BtNrnj3J.js";
 import "./logger-KeHncl-f.js";
-import "./dist-Bc0-6VcX.js";
-import "./manifest-read-D_HmoOcb.js";
+import "./dist-BUDAiEaH.js";
+import "./manifest-read-CKmTZKA5.js";
 import "./work-graph-repository-DZyJv5pV.js";
 import "./decisions-CzSIEeGP.js";
 

package/dist/{index-Ce8BVUmL.d.ts → index-CyQhVXLB.d.ts}

@@ -1333,6 +1333,16 @@ declare class CodexCLIAdapter implements WorkerAdapter {
    * Build spawn command for a coding task.
    * Uses: `codex exec` with prompt delivered via stdin.
    *
+   * `--sandbox workspace-write --ask-for-approval never` is required so the
+   * non-interactive `codex exec` can actually write files. Without flags, exec
+   * defaults to a read-only sandbox + an approval policy that escalates to the
+   * user — but exec has no one to approve, so file writes fail with
+   * "file change approval is not supported in exec mode" (→ create-story-no-file).
+   * `never` is exactly what Codex's own docs recommend for non-interactive runs,
+   * and this is normal automation mode — NOT the
+   * `--dangerously-bypass-approvals-and-sandbox` flag (which some org policies
+   * forbid). The planning command stays read-only (it must not write).
+   *
    * Do NOT use --json: it produces a JSONL event stream that prevents
    * extractYamlBlock from finding the structured result block in stdout.
    * Raw text output is required (same rationale as Claude adapter).
@@ -1439,4 +1449,4 @@ interface Recommendation {
 
 //#endregion
 export { AdapterDiscoveryResult, AdapterRegistry as AdapterRegistry$1, AdtError as AdtError$1, ClaudeCodeAdapter as ClaudeCodeAdapter$1, CodexCLIAdapter as CodexCLIAdapter$1, ConfigError as ConfigError$1, ConfigIncompatibleFormatError as ConfigIncompatibleFormatError$1, CoreEvents, DatabaseAdapter, DiscoveryReport, GeminiCLIAdapter as GeminiCLIAdapter$1, Recommendation, TypedEventBus };
-//# sourceMappingURL=index-Ce8BVUmL.d.ts.map
+//# sourceMappingURL=index-CyQhVXLB.d.ts.map

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AdapterDiscoveryResult, AdapterRegistry$1 as AdapterRegistry, AdtError$1 as AdtError, ClaudeCodeAdapter$1 as ClaudeCodeAdapter, CodexCLIAdapter$1 as CodexCLIAdapter, ConfigError$1 as ConfigError, ConfigIncompatibleFormatError$1 as ConfigIncompatibleFormatError, DiscoveryReport, GeminiCLIAdapter$1 as GeminiCLIAdapter, Recommendation, TypedEventBus } from "./index-Ce8BVUmL.js";
+import { AdapterDiscoveryResult, AdapterRegistry$1 as AdapterRegistry, AdtError$1 as AdtError, ClaudeCodeAdapter$1 as ClaudeCodeAdapter, CodexCLIAdapter$1 as CodexCLIAdapter, ConfigError$1 as ConfigError, ConfigIncompatibleFormatError$1 as ConfigIncompatibleFormatError, DiscoveryReport, GeminiCLIAdapter$1 as GeminiCLIAdapter, Recommendation, TypedEventBus } from "./index-CyQhVXLB.js";
 import pino from "pino";
 import { z } from "zod";
 import { Readable, Writable } from "node:stream";
@@ -1014,6 +1014,7 @@ declare const SubstrateConfigSchema: z.ZodObject<{
   default_agent: z.ZodOptional<z.ZodString>;
   supervisor_poll_interval_seconds: z.ZodOptional<z.ZodNumber>;
   retry_budget: z.ZodOptional<z.ZodNumber>;
+  epics_path: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 type SubstrateConfig = z.infer<typeof SubstrateConfigSchema>;
 

package/dist/index.js

@@ -1,8 +1,8 @@
 import { childLogger, createLogger, logger } from "./logger-KeHncl-f.js";
 import { assertDefined, createEventBus, createTuiApp, deepClone, formatDuration, generateId, isPlainObject, isTuiCapable, printNonTtyWarning, sleep, withRetry } from "./helpers-CElYrONe.js";
-import { AdapterRegistry, AdtError, ClaudeCodeAdapter, CodexCLIAdapter, ConfigError, ConfigIncompatibleFormatError, GeminiCLIAdapter } from "./dist-Bc0-6VcX.js";
+import { AdapterRegistry, AdtError, ClaudeCodeAdapter, CodexCLIAdapter, ConfigError, ConfigIncompatibleFormatError, GeminiCLIAdapter } from "./dist-BUDAiEaH.js";
 import "./adapter-registry-DIcrxjH8.js";
-import { BudgetExceededError, GitError, RecoveryError, TaskConfigError, TaskGraphCycleError, TaskGraphError, TaskGraphIncompatibleFormatError, WorkerError, WorkerNotFoundError } from "./errors-CwQM_6Yk.js";
+import { BudgetExceededError, GitError, RecoveryError, TaskConfigError, TaskGraphCycleError, TaskGraphError, TaskGraphIncompatibleFormatError, WorkerError, WorkerNotFoundError } from "./errors-pJaYVCUJ.js";
 
 //#region src/core/di.ts
 /**

package/dist/{interactive-prompt-y6udulxR.js → interactive-prompt-DKNFNQ7u.js}

@@ -1,5 +1,5 @@
 import { createLogger } from "./logger-KeHncl-f.js";
-import { readCurrentRunId, resolveMainRepoRoot } from "./manifest-read-D_HmoOcb.js";
+import { readCurrentRunId, resolveMainRepoRoot } from "./manifest-read-CKmTZKA5.js";
 import { join } from "node:path";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import * as readline from "node:readline";
@@ -180,4 +180,4 @@ async function runInteractivePrompt(decisionContext) {
 
 //#endregion
 export { runInteractivePrompt };
-//# sourceMappingURL=interactive-prompt-y6udulxR.js.map
+//# sourceMappingURL=interactive-prompt-DKNFNQ7u.js.map

package/dist/{manifest-read-D_HmoOcb.js → manifest-read-CKmTZKA5.js}

@@ -1,5 +1,5 @@
 import { createLogger } from "./logger-KeHncl-f.js";
-import { LEARNING_FINDING, createDecision, getDecisionsByCategory } from "./dist-Bc0-6VcX.js";
+import { LEARNING_FINDING, createDecision, getDecisionsByCategory } from "./dist-BUDAiEaH.js";
 import * as path$1 from "path";
 import { join } from "path";
 import { readFile } from "fs/promises";
@@ -5851,4 +5851,4 @@ async function resolveRunManifest(dbRoot, runId) {
 
 //#endregion
 export { FindingsInjector, RunManifest, RuntimeProbeListSchema, SupervisorLock, ZERO_FINDINGS_BY_AUTHOR, ZERO_FINDING_COUNTS, ZERO_PROBE_AUTHOR_METRICS, aggregateProbeAuthorMetrics, applyConfigToGraph, createDefaultVerificationPipeline, createGraphOrchestrator, createSdlcCodeReviewHandler, createSdlcCreateStoryHandler, createSdlcDevStoryHandler, createSdlcPhaseHandler, detectsEventDrivenAC, detectsStateIntegratingAC, extractTargetFilesFromStoryContent, parseRuntimeProbes, readCurrentRunId, renderFindings, resolveGraphPath, resolveMainRepoRoot, resolveRunManifest, rollupFindingCounts, rollupFindingsByAuthor, rollupProbeAuthorByClass, rollupProbeAuthorMetrics, runAcTraceabilityCheck, runStaleVerificationRecovery };
-//# sourceMappingURL=manifest-read-D_HmoOcb.js.map
+//# sourceMappingURL=manifest-read-CKmTZKA5.js.map

package/dist/modules/interactive-prompt/index.js

@@ -1,6 +1,6 @@
 import "../../logger-KeHncl-f.js";
-import "../../dist-Bc0-6VcX.js";
-import "../../manifest-read-D_HmoOcb.js";
-import { runInteractivePrompt } from "../../interactive-prompt-y6udulxR.js";
+import "../../dist-BUDAiEaH.js";
+import "../../manifest-read-CKmTZKA5.js";
+import { runInteractivePrompt } from "../../interactive-prompt-DKNFNQ7u.js";
 
 export { runInteractivePrompt };

package/dist/{routing-DFwoxEpT.js → routing-CEd36PVz.js}

@@ -1,4 +1,4 @@
-import { ModelRoutingConfigSchema, ProviderPolicySchema, RoutingConfigError, RoutingRecommender, RoutingResolver, RoutingTelemetry, RoutingTokenAccumulator, RoutingTuner, TASK_TYPE_PHASE_MAP, getModelTier, loadModelRoutingConfig } from "./dist-Bc0-6VcX.js";
+import { ModelRoutingConfigSchema, ProviderPolicySchema, RoutingConfigError, RoutingRecommender, RoutingResolver, RoutingTelemetry, RoutingTokenAccumulator, RoutingTuner, TASK_TYPE_PHASE_MAP, getModelTier, loadModelRoutingConfig } from "./dist-BUDAiEaH.js";
 import "./routing-DFxoKHDt.js";
 
 export { loadModelRoutingConfig };

package/dist/{run-BsPkkWob.js → run-BMx6kY0E.js}

@@ -1,14 +1,14 @@
-import "./health-C5qUaNup.js";
+import "./health-BtNrnj3J.js";
 import "./logger-KeHncl-f.js";
 import "./helpers-CElYrONe.js";
-import "./dist-Bc0-6VcX.js";
-import { normalizeGraphSummaryToStatus, registerRunCommand, resolveMaxReviewCycles, resolveProbeAuthorStateIntegrating, runRunAction, wireNdjsonEmitter } from "./run-jVpLtRRy.js";
-import "./manifest-read-D_HmoOcb.js";
+import "./dist-BUDAiEaH.js";
+import { normalizeGraphSummaryToStatus, registerRunCommand, resolveMaxReviewCycles, resolveProbeAuthorStateIntegrating, runRunAction, wireNdjsonEmitter } from "./run-DAb4BgAO.js";
+import "./manifest-read-CKmTZKA5.js";
 import "./routing-DFxoKHDt.js";
 import "./work-graph-repository-DZyJv5pV.js";
 import "./decisions-CzSIEeGP.js";
 import "./decision-router-DblHY8se.js";
-import "./interactive-prompt-y6udulxR.js";
+import "./interactive-prompt-DKNFNQ7u.js";
 import "./recovery-engine-BKGBeBnW.js";
 
 export { runRunAction };

package/dist/{run-jVpLtRRy.js → run-DAb4BgAO.js}

@@ -1,15 +1,16 @@
-import { BMAD_BASELINE_TOKENS_FULL, FileKvStore, STOP_AFTER_VALID_PHASES, STORY_KEY_PATTERN, VALID_PHASES, __commonJS, __require, __toESM, buildPipelineStatusOutput, createDatabaseAdapter, formatOutput, formatPipelineSummary, formatTokenTelemetry, inspectProcessTree, parseDbTimestampAsUtc, validateStoryKey } from "./health-C5qUaNup.js";
+import { BMAD_BASELINE_TOKENS_FULL, FileKvStore, STOP_AFTER_VALID_PHASES, STORY_KEY_PATTERN, VALID_PHASES, __commonJS, __require, __toESM, buildPipelineStatusOutput, createDatabaseAdapter, formatOutput, formatPipelineSummary, formatTokenTelemetry, inspectProcessTree, parseDbTimestampAsUtc, validateStoryKey } from "./health-BtNrnj3J.js";
 import { createLogger } from "./logger-KeHncl-f.js";
 import { TypedEventBusImpl, createEventBus, createTuiApp, isTuiCapable, printNonTtyWarning, sleep } from "./helpers-CElYrONe.js";
-import { ADVISORY_NOTES, Categorizer, ConsumerAnalyzer, DEFAULT_GLOBAL_SETTINGS, DispatcherImpl, DoltClient, ESCALATION_DIAGNOSIS, EXPERIMENT_RESULT, EfficiencyScorer, IngestionServer, LogTurnAnalyzer, OPERATIONAL_FINDING, Recommender, RoutingRecommender, RoutingResolver, RoutingTelemetry, RoutingTokenAccumulator, RoutingTuner, STORY_METRICS, STORY_OUTCOME, SubstrateConfigSchema, TEST_EXPANSION_FINDING, TEST_PLAN, TelemetryNormalizer, TelemetryPipeline, TurnAnalyzer, addTokenUsage, aggregateTokenUsageForRun, aggregateTokenUsageForStory, callLLM, classifyVersionGap, createConfigSystem, createDatabaseAdapter$1, createDecision, createPipelineRun, createRequirement, createStderrLogger, detectInterfaceChanges, getArtifactByTypeForRun, getArtifactsByRun, getDecisionsByCategory, getDecisionsByPhase, getDecisionsByPhaseForRun, getLatestRun, getPipelineRunById, getRunMetrics, getRunningPipelineRuns, getStoryMetricsForRun, getTokenUsageSummary, initSchema, listRequirements, loadModelRoutingConfig, registerArtifact, swallowDebug, updatePipelineRun, updatePipelineRunConfig, upsertDecision, writeRunMetrics, writeStoryMetrics } from "./dist-Bc0-6VcX.js";
-import { FindingsInjector, RunManifest, RuntimeProbeListSchema, applyConfigToGraph, createDefaultVerificationPipeline, createGraphOrchestrator, createSdlcCodeReviewHandler, createSdlcCreateStoryHandler, createSdlcDevStoryHandler, createSdlcPhaseHandler, detectsEventDrivenAC, detectsStateIntegratingAC, extractTargetFilesFromStoryContent, parseRuntimeProbes, renderFindings, resolveGraphPath, resolveMainRepoRoot, runAcTraceabilityCheck, runStaleVerificationRecovery } from "./manifest-read-D_HmoOcb.js";
+import { ADVISORY_NOTES, CODEX_SANDBOX_BLOCK_HINT, Categorizer, ConsumerAnalyzer, DEFAULT_GLOBAL_SETTINGS, DispatcherImpl, DoltClient, ESCALATION_DIAGNOSIS, EXPERIMENT_RESULT, EfficiencyScorer, IngestionServer, LogTurnAnalyzer, OPERATIONAL_FINDING, Recommender, RoutingRecommender, RoutingResolver, RoutingTelemetry, RoutingTokenAccumulator, RoutingTuner, STORY_METRICS, STORY_OUTCOME, SubstrateConfigSchema, TEST_EXPANSION_FINDING, TEST_PLAN, TelemetryNormalizer, TelemetryPipeline, TurnAnalyzer, addTokenUsage, aggregateTokenUsageForRun, aggregateTokenUsageForStory, callLLM, classifyVersionGap, createConfigSystem, createDatabaseAdapter$1, createDecision, createPipelineRun, createRequirement, createStderrLogger, detectCodexSandboxBlock, detectInterfaceChanges, getArtifactByTypeForRun, getArtifactsByRun, getDecisionsByCategory, getDecisionsByPhase, getDecisionsByPhaseForRun, getLatestRun, getPipelineRunById, getRunMetrics, getRunningPipelineRuns, getStoryMetricsForRun, getTokenUsageSummary, initSchema, listRequirements, loadModelRoutingConfig, registerArtifact, swallowDebug, updatePipelineRun, updatePipelineRunConfig, upsertDecision, writeRunMetrics, writeStoryMetrics } from "./dist-BUDAiEaH.js";
+import { FindingsInjector, RunManifest, RuntimeProbeListSchema, applyConfigToGraph, createDefaultVerificationPipeline, createGraphOrchestrator, createSdlcCodeReviewHandler, createSdlcCreateStoryHandler, createSdlcDevStoryHandler, createSdlcPhaseHandler, detectsEventDrivenAC, detectsStateIntegratingAC, extractTargetFilesFromStoryContent, parseRuntimeProbes, renderFindings, resolveGraphPath, resolveMainRepoRoot, runAcTraceabilityCheck, runStaleVerificationRecovery } from "./manifest-read-CKmTZKA5.js";
 import { WorkGraphRepository, detectCycles } from "./work-graph-repository-DZyJv5pV.js";
 import { deriveExitCode, routeDecision } from "./decision-router-DblHY8se.js";
-import { runInteractivePrompt } from "./interactive-prompt-y6udulxR.js";
+import { runInteractivePrompt } from "./interactive-prompt-DKNFNQ7u.js";
 import { runRecoveryEngine } from "./recovery-engine-BKGBeBnW.js";
 import { basename, dirname, extname, join } from "path";
 import { access, readFile, readdir, stat } from "fs/promises";
 import { EventEmitter } from "node:events";
+import * as yaml$1 from "js-yaml";
 import yaml from "js-yaml";
 import * as actualFS from "node:fs";
 import { accessSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, unwatchFile, watchFile, writeFileSync } from "node:fs";
@@ -135,23 +136,29 @@ async function verifyGitVersion() {
 	}
 }
 /**
-* Create a git worktree and its associated branch.
+* Decide whether a registered worktree from a prior dispatch can be reclaimed
+* for a fresh re-run. Safe only when there is nothing to lose: no uncommitted
+* changes AND no commits on the branch beyond the base branch. A negative
+* `commitsAhead` means the ahead-count could not be determined → not safe.
 *
-* Uses a single `git worktree add {worktreePath} -b {branchName} {baseBranch}`
-* command to create the worktree with a new branch in one step.
-*
-* @param projectRoot - Absolute path to the git repository root
-* @param taskId      - Task identifier (used in path derivation)
-* @param branchName  - Branch name to create (e.g., "substrate/story-abc123")
-* @param baseBranch  - Branch to base the worktree on (e.g., "main")
-* @param copyFiles   - v0.20.109: Optional list of files to copy from the
-*                      project root into the new worktree after creation
-*                      (e.g., `[".env", ".env.local"]`). Missing files are
-*                      skipped silently. Useful for gitignored files that
-*                      build tooling needs but `git worktree add` won't carry.
-* @returns           - Object with the worktreePath
-* @throws            - Error if git command fails
+* Pure + exported for testing (the git I/O that produces the inputs lives in
+* createWorktree).
 */
+function decideWorktreeReclaim(hasUncommittedChanges, commitsAhead, baseBranch) {
+	if (hasUncommittedChanges) return {
+		safe: false,
+		reason: "it has uncommitted changes that are NOT on the branch"
+	};
+	if (commitsAhead > 0) return {
+		safe: false,
+		reason: `its branch has ${String(commitsAhead)} commit(s) beyond ${baseBranch}`
+	};
+	if (commitsAhead < 0) return {
+		safe: false,
+		reason: "its state could not be verified as safe to discard"
+	};
+	return { safe: true };
+}
 async function createWorktree(projectRoot, taskId, branchName, baseBranch, copyFiles = []) {
 	const worktreePath = path$5.join(projectRoot, ".substrate-worktrees", taskId);
 	const worktreeExists = await access$1(worktreePath).then(() => true).catch((err) => {
@@ -170,7 +177,29 @@ async function createWorktree(projectRoot, taskId, branchName, baseBranch, copyF
 			recursive: true,
 			force: true
 		});
-		else throw new Error(`Worktree at ${worktreePath} is already registered (branch: ${branchName}).\nThis usually means a prior dispatch escalated and the worktree was preserved for inspection.\nIt may contain uncommitted changes that are NOT on the branch — inspect before removing.\n\nTo remove and re-dispatch:\n  substrate worktrees --cleanup ${taskId}\n\nTo remove all substrate worktrees:\n  substrate worktrees --cleanup`);
+		else {
+			const statusResult = await spawnGit(["status", "--porcelain"], { cwd: worktreePath });
+			const hasUncommittedChanges = statusResult.code === 0 && statusResult.stdout.trim().length > 0;
+			const aheadResult = await spawnGit([
+				"rev-list",
+				"--count",
+				`${baseBranch}..${branchName}`
+			], { cwd: projectRoot });
+			const commitsAhead = aheadResult.code === 0 ? Number.parseInt(aheadResult.stdout.trim(), 10) || 0 : -1;
+			const decision = decideWorktreeReclaim(hasUncommittedChanges, commitsAhead, baseBranch);
+			if (!decision.safe) throw new Error(`Worktree at ${worktreePath} is already registered (branch: ${branchName}) and ${decision.reason}.\nIt was preserved from a prior dispatch for inspection — inspect before removing.\n\nTo remove and re-dispatch:\n  substrate worktrees --cleanup ${taskId}\n\nTo remove all substrate worktrees:\n  substrate worktrees --cleanup`);
+			await spawnGit([
+				"worktree",
+				"remove",
+				"--force",
+				worktreePath
+			], { cwd: projectRoot });
+			await spawnGit([
+				"branch",
+				"-D",
+				branchName
+			], { cwd: projectRoot });
+		}
 	}
 	const addResult = await spawnGit([
 		"worktree",
@@ -6484,6 +6513,64 @@ const ProbeAuthorResultSchema = z.object({
 	probes: InlineRuntimeProbeListSchema
 });
 
+//#endregion
+//#region src/modules/implementation-orchestrator/epic-paths.ts
+/** Default planning directories scanned for per-epic/glob files, priority order. */
+const DEFAULT_PLANNING_DIRS = [
+	"_bmad-output/planning-artifacts",
+	"_bmad-output",
+	"docs/planning"
+];
+/** Default consolidated-epics file candidates (relative), priority order. */
+const DEFAULT_EPICS_FILES = [
+	"_bmad-output/planning-artifacts/epics.md",
+	"_bmad-output/epics.md",
+	"docs/planning/epics.md"
+];
+function normalizeOverride(projectRoot, override) {
+	if (override === void 0 || override.trim().length === 0) return void 0;
+	const trimmed = override.trim();
+	return isAbsolute(trimmed) ? trimmed : join$1(projectRoot, trimmed);
+}
+/**
+* Ordered absolute candidate paths for the consolidated epics file. An override
+* (if any) is highest priority, followed by the built-in defaults.
+*/
+function buildEpicsFileCandidates(projectRoot, epicsPathOverride) {
+	const out = [];
+	const abs = normalizeOverride(projectRoot, epicsPathOverride);
+	if (abs !== void 0) out.push(abs);
+	for (const rel of DEFAULT_EPICS_FILES) out.push(join$1(projectRoot, rel));
+	return out;
+}
+/**
+* Ordered absolute planning directories to scan for per-epic/glob files. When an
+* override file is given, its parent directory is searched first.
+*/
+function buildPlanningDirs(projectRoot, epicsPathOverride) {
+	const out = [];
+	const abs = normalizeOverride(projectRoot, epicsPathOverride);
+	if (abs !== void 0) out.push(dirname$1(abs));
+	for (const rel of DEFAULT_PLANNING_DIRS) out.push(join$1(projectRoot, rel));
+	return out;
+}
+/**
+* Best-effort read of `epics_path` from `<projectRoot>/.substrate/config.yaml`.
+* Returns undefined on any error (missing file, parse failure, wrong type) so
+* discovery silently falls back to the defaults.
+*/
+function resolveEpicsPathOverride(projectRoot) {
+	try {
+		const configPath = join$1(projectRoot, ".substrate", "config.yaml");
+		if (!existsSync(configPath)) return void 0;
+		const parsed = yaml$1.load(readFileSync(configPath, "utf-8"));
+		const value = parsed?.epics_path;
+		return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
+	} catch {
+		return void 0;
+	}
+}
+
 //#endregion
 //#region src/modules/compiled-workflows/token-ceiling.ts
 /**
@@ -7214,7 +7301,8 @@ async function getArchConstraints$3(deps) {
 */
 function readEpicShardFromFile(projectRoot, epicId, storyKey) {
 	try {
-		const candidates = [join$1(projectRoot, "_bmad-output", "planning-artifacts", "epics.md"), join$1(projectRoot, "_bmad-output", "epics.md")];
+		const override = resolveEpicsPathOverride(projectRoot);
+		const candidates = buildEpicsFileCandidates(projectRoot, override);
 		const epicsPath = candidates.find((p) => existsSync(p));
 		const epicNum = epicId.replace(/^epic-/i, "");
 		if (epicsPath) {
@@ -7232,25 +7320,27 @@ function readEpicShardFromFile(projectRoot, epicId, storyKey) {
 				return content.slice(startIdx, endIdx).trim();
 			}
 		}
-		const planningDir = join$1(projectRoot, "_bmad-output", "planning-artifacts");
-		if (existsSync(planningDir)) try {
-			const entries = readdirSync(planningDir, { encoding: "utf-8" });
-			const perEpicPattern = new RegExp(`^epic-${epicNum}-.*\\.md$`);
-			const matches = entries.filter((e) => perEpicPattern.test(e)).sort();
-			if (matches.length > 0) {
-				let chosenIdx = 0;
-				if (storyKey !== void 0 && matches.length > 1) for (let i = 0; i < matches.length; i++) {
-					const candidateContent = readFileSync(join$1(planningDir, matches[i]), "utf-8");
-					if (extractStorySection(candidateContent, storyKey) !== null) {
-						chosenIdx = i;
-						break;
+		const perEpicPattern = new RegExp(`^epic-${epicNum}-.*\\.md$`);
+		for (const planningDir of buildPlanningDirs(projectRoot, override)) {
+			if (!existsSync(planningDir)) continue;
+			try {
+				const entries = readdirSync(planningDir, { encoding: "utf-8" });
+				const matches = entries.filter((e) => perEpicPattern.test(e)).sort();
+				if (matches.length > 0) {
+					let chosenIdx = 0;
+					if (storyKey !== void 0 && matches.length > 1) for (let i = 0; i < matches.length; i++) {
+						const candidateContent = readFileSync(join$1(planningDir, matches[i]), "utf-8");
+						if (extractStorySection(candidateContent, storyKey) !== null) {
+							chosenIdx = i;
+							break;
+						}
 					}
+					const perEpicPath = join$1(planningDir, matches[chosenIdx]);
+					const content = readFileSync(perEpicPath, "utf-8");
+					return content.trim();
 				}
-				const perEpicPath = join$1(planningDir, matches[chosenIdx]);
-				const content = readFileSync(perEpicPath, "utf-8");
-				return content.trim();
-			}
-		} catch {}
+			} catch {}
+		}
 		return "";
 	} catch (err) {
 		logger$21.warn({
@@ -12685,17 +12775,16 @@ function discoverPendingStoryKeys(projectRoot, epicNumber) {
 * For individual epic files, use findEpicFiles() instead.
 */
 function findEpicsFile(projectRoot) {
-	const candidates = ["_bmad-output/planning-artifacts/epics.md", "_bmad-output/epics.md"];
-	for (const candidate of candidates) {
-		const fullPath = join$1(projectRoot, candidate);
-		if (existsSync(fullPath)) return fullPath;
+	const override = resolveEpicsPathOverride(projectRoot);
+	for (const fullPath of buildEpicsFileCandidates(projectRoot, override)) if (existsSync(fullPath)) return fullPath;
+	for (const planningDir of buildPlanningDirs(projectRoot, override)) {
+		if (!existsSync(planningDir)) continue;
+		try {
+			const entries = readdirSync(planningDir, { encoding: "utf-8" });
+			const match$2 = entries.filter((e) => /^epics[-.].*\.md$/i.test(e) && !/^epic-\d+/.test(e)).sort();
+			if (match$2.length > 0) return join$1(planningDir, match$2[0]);
+		} catch {}
 	}
-	const planningDir = join$1(projectRoot, "_bmad-output", "planning-artifacts");
-	if (existsSync(planningDir)) try {
-		const entries = readdirSync(planningDir, { encoding: "utf-8" });
-		const match$2 = entries.filter((e) => /^epics[-.].*\.md$/i.test(e) && !/^epic-\d+/.test(e)).sort();
-		if (match$2.length > 0) return join$1(planningDir, match$2[0]);
-	} catch {}
 	return void 0;
 }
 /**
@@ -12703,14 +12792,15 @@ function findEpicsFile(projectRoot) {
 * Returns paths sorted alphabetically.
 */
 function findEpicFiles(projectRoot) {
-	const planningDir = join$1(projectRoot, "_bmad-output", "planning-artifacts");
-	if (!existsSync(planningDir)) return [];
-	try {
-		const entries = readdirSync(planningDir, { encoding: "utf-8" });
-		return entries.filter((e) => /^epic-\d+.*\.md$/.test(e)).sort().map((e) => join$1(planningDir, e));
-	} catch {
-		return [];
+	const out = [];
+	for (const planningDir of buildPlanningDirs(projectRoot, resolveEpicsPathOverride(projectRoot))) {
+		if (!existsSync(planningDir)) continue;
+		try {
+			const entries = readdirSync(planningDir, { encoding: "utf-8" });
+			for (const e of entries.filter((x) => /^epic-\d+.*\.md$/.test(x)).sort()) out.push(join$1(planningDir, e));
+		} catch {}
 	}
+	return out;
 }
 /**
 * Story 61-3: find the epic file relevant to a specific story.
@@ -12753,14 +12843,15 @@ function findEpicFileForStory(projectRoot, storyKey) {
 	const epicNumMatch = /^(\d+)/.exec(storyKey);
 	if (!epicNumMatch) return void 0;
 	const epicNum = epicNumMatch[1];
-	const planningDir = join$1(projectRoot, "_bmad-output", "planning-artifacts");
-	if (!existsSync(planningDir)) return void 0;
-	try {
-		const entries = readdirSync(planningDir, { encoding: "utf-8" });
-		const perEpicPattern = new RegExp(`^epic-${epicNum}-.*\\.md$`);
-		const matches = entries.filter((e) => perEpicPattern.test(e)).sort();
-		if (matches.length > 0) return join$1(planningDir, matches[0]);
-	} catch {}
+	const perEpicPattern = new RegExp(`^epic-${epicNum}-.*\\.md$`);
+	for (const planningDir of buildPlanningDirs(projectRoot, resolveEpicsPathOverride(projectRoot))) {
+		if (!existsSync(planningDir)) continue;
+		try {
+			const entries = readdirSync(planningDir, { encoding: "utf-8" });
+			const matches = entries.filter((e) => perEpicPattern.test(e)).sort();
+			if (matches.length > 0) return join$1(planningDir, matches[0]);
+		} catch {}
+	}
 	return void 0;
 }
 /**
@@ -14244,11 +14335,12 @@ function createImplementationOrchestrator(deps) {
 						completedAt: new Date().toISOString()
 					});
 					await writeStoryMetricsBestEffort(storyKey, "failed", 0);
+					const codexHint = detectCodexSandboxBlock(errMsg);
 					await emitEscalation({
 						storyKey,
 						lastVerdict: "create-story-failed",
 						reviewCycles: 0,
-						issues: [errMsg]
+						issues: codexHint !== null ? [errMsg, codexHint] : [errMsg]
 					});
 					await persistState();
 					return;
@@ -14331,11 +14423,12 @@ function createImplementationOrchestrator(deps) {
 								completedAt: new Date().toISOString()
 							});
 							await writeStoryMetricsBestEffort(storyKey, "failed", 0);
+							const fraudIssues = deps.agentId === "codex" ? [errMsg, CODEX_SANDBOX_BLOCK_HINT] : [errMsg];
 							await emitEscalation({
 								storyKey,
 								lastVerdict: "create-story-fraud-success",
 								reviewCycles: 0,
-								issues: [errMsg]
+								issues: fraudIssues
 							});
 							await persistState();
 							return;
@@ -21476,6 +21569,47 @@ async function runResearchPhase(deps, params) {
 	}
 }
 
+//#endregion
+//#region src/modules/config/resolve-default-agent.ts
+/**
+* Maps config provider keys to the dispatch agent ids the registry/orchestrator
+* use. The config keys (`claude`/`codex`/`gemini`) differ from the adapter ids
+* (`claude-code`/`codex`/`gemini`) only for Claude.
+*/
+const PROVIDER_TO_AGENT = {
+	claude: "claude-code",
+	codex: "codex",
+	gemini: "gemini"
+};
+/**
+* Precedence when more than one provider is enabled and no `--agent` is given.
+* Claude first (substrate's reference provider), then Codex, then Gemini.
+*/
+const PROVIDER_PRECEDENCE = [
+	"claude",
+	"codex",
+	"gemini"
+];
+/**
+* Returns the dispatch agent id derived from the enabled providers:
+*  - exactly one enabled → that provider's agent id
+*  - several enabled     → the highest-precedence enabled provider
+*  - none enabled        → `{ error }` (no agent can be chosen)
+*
+* Providers absent from the precedence list (future provider keys) sort after
+* the known ones but remain selectable.
+*/
+function resolveDefaultAgentId(providers) {
+	const enabled = Object.entries(providers).filter(([, cfg]) => cfg?.enabled === true).map(([key]) => key);
+	if (enabled.length === 0) return { error: "No enabled providers in .substrate/config.yaml. Run `substrate init` and enable at least one CLI, or pass --agent <claude-code|codex|gemini>." };
+	const rankOf = (p) => {
+		const i = PROVIDER_PRECEDENCE.indexOf(p);
+		return i === -1 ? Number.MAX_SAFE_INTEGER : i;
+	};
+	const chosen = [...enabled].sort((a, b) => rankOf(a) - rankOf(b))[0];
+	return { agentId: PROVIDER_TO_AGENT[chosen] ?? chosen };
+}
+
 //#endregion
 //#region src/modules/telemetry/mesh-reporter.ts
 const logger$2 = createLogger("mesh-reporter");
@@ -44658,10 +44792,10 @@ function createTwinManager(eventBus, options) {
 			} catch {
 				throw new TwinError("Docker not found — twins require Docker");
 			}
-			const yaml$1 = generateComposeYaml(twins);
+			const yaml$2 = generateComposeYaml(twins);
 			const dir = join$1(tmpdir(), randomUUID());
 			mkdirSync(dir, { recursive: true });
-			writeFileSync(join$1(dir, "docker-compose.yml"), yaml$1, "utf-8");
+			writeFileSync(join$1(dir, "docker-compose.yml"), yaml$2, "utf-8");
 			composeDir = dir;
 			startedTwins = twins;
 			try {
@@ -45800,7 +45934,7 @@ function resolveProbeAuthorStateIntegrating(cliFlag) {
 *   substrate run --non-interactive --halt-on none --events --output-format json
 */
 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, skipVerification, epic: epicNumber, dryRun, maxReviewCycles = 2, engine, agent: agentId, registry: injectedRegistry, haltOn: haltOnOpt, costCeiling, probeAuthor, probeAuthorStateIntegrating: probeAuthorStateIntegratingFlag, nonInteractive, verifyAc, noWorktree } = 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, skipVerification, epic: epicNumber, dryRun, maxReviewCycles = 2, engine, agent: explicitAgentId, registry: injectedRegistry, haltOn: haltOnOpt, costCeiling, probeAuthor, probeAuthorStateIntegrating: probeAuthorStateIntegratingFlag, nonInteractive, verifyAc, noWorktree } = options;
 	const haltOn = haltOnOpt;
 	const VALID_PROBE_AUTHOR_MODES = [
 		"enabled",
@@ -45845,7 +45979,8 @@ async function runRunAction(options) {
 		else process.stderr.write(`Error: ${errorMsg}\n`);
 		return 1;
 	}
-	const effectiveMaxReviewCycles = resolveMaxReviewCycles(maxReviewCycles, agentId, injectedRegistry);
+	let agentId = explicitAgentId;
+	let agentResolutionError;
 	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");
@@ -45920,6 +46055,13 @@ async function runRunAction(options) {
 		const configSystem = createConfigSystem({ projectConfigDir: dbDir });
 		await configSystem.load();
 		const cfg = configSystem.getConfig();
+		if (agentId == null) {
+			const resolved = resolveDefaultAgentId(cfg.providers);
+			if (resolved.agentId != null) {
+				agentId = resolved.agentId;
+				logger.info({ agentId }, "Resolved default dispatch agent from enabled providers");
+			} else agentResolutionError = resolved.error;
+		}
 		tokenCeilings = cfg.token_ceilings;
 		if (cfg.dispatch_timeouts) {
 			dispatchTimeouts = Object.fromEntries(Object.entries(cfg.dispatch_timeouts).filter(([, v]) => v !== void 0));
@@ -45941,6 +46083,12 @@ async function runRunAction(options) {
 	} catch {
 		logger.debug("Config loading skipped — using default token ceilings and telemetry settings");
 	}
+	if (agentResolutionError !== void 0) {
+		if (outputFormat === "json") process.stdout.write(formatOutput(null, "json", false, agentResolutionError) + "\n");
+		else process.stderr.write(`Error: ${agentResolutionError}\n`);
+		return 1;
+	}
+	const effectiveMaxReviewCycles = resolveMaxReviewCycles(maxReviewCycles, agentId, injectedRegistry);
 	let parsedStoryKeys = [];
 	if (storiesArg !== void 0 && storiesArg !== "") {
 		parsedStoryKeys = storiesArg.split(",").map((k) => k.trim()).filter((k) => k.length > 0);
@@ -46117,7 +46265,7 @@ async function runRunAction(options) {
 			})
 		});
 		try {
-			const runsDir = join(dbDir, "runs");
+			const runsDir$1 = join(dbDir, "runs");
 			const cliFlags = {
 				...parsedStoryKeys.length > 0 ? { stories: parsedStoryKeys } : {},
 				halt_on: haltOn ?? "critical",
@@ -46128,7 +46276,7 @@ async function runRunAction(options) {
 				...nonInteractive === true ? { non_interactive: true } : {},
 				...noWorktree === true ? { no_worktree: true } : {}
 			};
-			const manifest = RunManifest.open(pipelineRun.id, runsDir);
+			const manifest = RunManifest.open(pipelineRun.id, runsDir$1);
 			await manifest.patchCLIFlags(cliFlags);
 			await manifest.update({ run_status: "running" });
 		} catch (err) {
@@ -46258,6 +46406,16 @@ async function runRunAction(options) {
 				process.stdout.write(sep$2 + "\n");
 				for (const s$1 of storiesPreview) for (const p of s$1.phases) process.stdout.write(s$1.storyKey.padEnd(COL.story) + p.phase.padEnd(COL.phase) + p.model.padEnd(COL.model) + String(p.estimatedSymbolCount) + "\n");
 			}
+			try {
+				await RunManifest.open(pipelineRun.id, join(dbDir, "runs")).update({ run_status: "completed" });
+			} catch (err) {
+				logger.debug({ err }, "Failed to finalize dry-run manifest (non-fatal)");
+			}
+			try {
+				await updatePipelineRun(adapter, pipelineRun.id, { status: "completed" });
+			} catch (err) {
+				logger.debug({ err }, "Failed to finalize dry-run Dolt pipeline_runs (non-fatal)");
+			}
 			return 0;
 		}
 		const dispatcher = createDispatcher({
@@ -46646,11 +46804,16 @@ async function runRunAction(options) {
 		} catch (metricsErr) {
 			logger.warn({ err: metricsErr }, "Failed to write run metrics (best-effort)");
 		}
+		const runsDir = join(dbDir, "runs");
+		const terminalStatus = failedKeys.length > 0 || escalatedKeys.length > 0 ? "failed" : "completed";
 		try {
-			const runsDir = join(dbDir, "runs");
-			const terminalStatus = failedKeys.length > 0 || escalatedKeys.length > 0 ? "failed" : "completed";
 			await RunManifest.open(pipelineRun.id, runsDir).update({ run_status: terminalStatus });
 		} catch {}
+		try {
+			await updatePipelineRun(adapter, pipelineRun.id, { status: terminalStatus });
+		} catch (err) {
+			logger.debug({ err }, "Failed to finalize Dolt pipeline_runs status (non-fatal)");
+		}
 		if (progressRenderer !== void 0) progressRenderer.render({
 			type: "pipeline:complete",
 			ts: new Date().toISOString(),
@@ -46708,8 +46871,8 @@ async function runRunAction(options) {
 					reason: "non-interactive: stdin prompt suppressed"
 				});
 				try {
-					const runsDir = join(dbDir, "runs");
-					const runManifestForHalt = RunManifest.open(pipelineRun.id, runsDir);
+					const runsDir$1 = join(dbDir, "runs");
+					const runManifestForHalt = RunManifest.open(pipelineRun.id, runsDir$1);
 					await runManifestForHalt.update({ cli_flags: {
 						halt_on: haltPolicy,
 						halt_skipped: true,
@@ -46736,8 +46899,8 @@ async function runRunAction(options) {
 			return derivedCode;
 		}
 		if (verifyAc === true) try {
-			const runsDir = join(dbDir, "runs");
-			const runManifestForAc = RunManifest.open(pipelineRun.id, runsDir);
+			const runsDir$1 = join(dbDir, "runs");
+			const runManifestForAc = RunManifest.open(pipelineRun.id, runsDir$1);
 			const manifestData = await runManifestForAc.read();
 			const artifactsDir = join(dbRoot, "_bmad-output", "implementation-artifacts");
 			const acResults = {};
@@ -47278,7 +47441,7 @@ async function runFullPipeline(options) {
 */
 async function emitPreDispatchVersionAdvisory(currentVersion) {
 	if (process.env["SUBSTRATE_NO_UPDATE_CHECK"] === "1") return;
-	const { createVersionManager } = await import("./version-manager-impl-BRVBwdma.js");
+	const { createVersionManager } = await import("./version-manager-impl-Bi05jQ9s.js");
 	const vm = createVersionManager();
 	const result = await vm.checkForUpdates(true);
 	const gap = classifyVersionGap(currentVersion, result.latestVersion);
@@ -47375,4 +47538,4 @@ function registerRunCommand(program, version = "0.0.0", projectRoot = process.cw
 
 //#endregion
 export { AdapterTelemetryPersistence, AppError, DoltRepoMapMetaRepository, DoltSymbolRepository, ERR_REPO_MAP_STORAGE_WRITE, EpicIngester, GLOBSTAR$1 as GLOBSTAR, GitClient, GrammarLoader, Minimatch$1 as Minimatch, Minipass, RepoMapInjector, RepoMapModule, RepoMapQueryEngine, RepoMapStorage, SymbolParser, createContextCompiler, createDispatcher, createEventEmitter, createGitWorktreeManager, createImplementationOrchestrator, createPackLoader, createPhaseOrchestrator, createStopAfterGate, createTelemetryAdvisor, escape$1 as escape, formatPhaseCompletionSummary, getFactoryRunSummaries, getScenarioResultsForRun, getTwinRunsForRun, listGraphRuns, normalizeGraphSummaryToStatus, registerExportCommand, registerFactoryCommand, registerRunCommand, registerScenariosCommand, resolveMaxReviewCycles, resolveProbeAuthorStateIntegrating, resolveStoryKeys, runAnalysisPhase, runPlanningPhase, runProbeAuthor, runRunAction, runSolutioningPhase, unescape$1 as unescape, validateStopAfterFromConflict, wireNdjsonEmitter };
-//# sourceMappingURL=run-jVpLtRRy.js.map
+//# sourceMappingURL=run-DAb4BgAO.js.map

package/dist/src/modules/recovery-engine/index.d.ts

@@ -1,4 +1,4 @@
-import { CoreEvents, DatabaseAdapter, TypedEventBus } from "../../../index-Ce8BVUmL.js";
+import { CoreEvents, DatabaseAdapter, TypedEventBus } from "../../../index-CyQhVXLB.js";
 import { z } from "zod";
 
 //#region packages/sdlc/dist/verification/findings.d.ts

package/dist/{upgrade-BlBDCOfS.js → upgrade-BApZ1sPK.js}

@@ -1,4 +1,4 @@
-import { createVersionManager } from "./dist-Bc0-6VcX.js";
+import { createVersionManager } from "./dist-BUDAiEaH.js";
 import { execSync, spawn } from "child_process";
 import * as readline from "readline";
 
@@ -123,4 +123,4 @@ function registerUpgradeCommand(program) {
 
 //#endregion
 export { isGlobalInstall, registerUpgradeCommand, runUpgradeCommand };
-//# sourceMappingURL=upgrade-BlBDCOfS.js.map
+//# sourceMappingURL=upgrade-BApZ1sPK.js.map

package/dist/{upgrade-OE6hMPMW.js → upgrade-D4Dj7rjQ.js}

@@ -1,5 +1,5 @@
-import "./dist-Bc0-6VcX.js";
+import "./dist-BUDAiEaH.js";
 import "./version-manager-impl-qFBiO4Eh.js";
-import { isGlobalInstall, registerUpgradeCommand, runUpgradeCommand } from "./upgrade-BlBDCOfS.js";
+import { isGlobalInstall, registerUpgradeCommand, runUpgradeCommand } from "./upgrade-BApZ1sPK.js";
 
 export { isGlobalInstall, registerUpgradeCommand, runUpgradeCommand };

package/dist/{version-manager-impl-BRVBwdma.js → version-manager-impl-Bi05jQ9s.js}

@@ -1,4 +1,4 @@
-import { VersionManagerImpl, createVersionManager } from "./dist-Bc0-6VcX.js";
+import { VersionManagerImpl, createVersionManager } from "./dist-BUDAiEaH.js";
 import "./version-manager-impl-qFBiO4Eh.js";
 
 export { createVersionManager };

package/package.json

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

package/dist/adapter-registry-B9G8dfn-.js

@@ -1,4 +0,0 @@
-import { AdapterRegistry } from "./dist-Bc0-6VcX.js";
-import "./adapter-registry-DIcrxjH8.js";
-
-export { AdapterRegistry };