substrate-ai 0.20.147 → 0.20.149

package/dist/{dist-DT378h1M.js → dist-C2CAZDep.js}

@@ -4,13 +4,15 @@ import { EventEmitter } from "node:events";
 import yaml, { dump, load } from "js-yaml";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { exec, execFile, execSync, spawn, spawnSync } from "node:child_process";
+import * as path$2 from "node:path";
+import * as path$1 from "node:path";
 import path, { dirname as dirname$1, join as join$1, resolve as resolve$1 } from "node:path";
-import os, { freemem, platform } from "node:os";
+import os, { freemem, homedir, platform } from "node:os";
 import { createHash, randomUUID } from "node:crypto";
 import { z } from "zod";
-import { access as access$1, mkdir as mkdir$1, readFile as readFile$1, writeFile as writeFile$1 } from "node:fs/promises";
+import { access as access$1, copyFile, mkdir as mkdir$1, readFile as readFile$1, readdir as readdir$1, rm, writeFile as writeFile$1 } from "node:fs/promises";
 import { readFileSync as readFileSync$1, writeFileSync as writeFileSync$1 } from "fs";
-import { homedir } from "os";
+import { homedir as homedir$1 } from "os";
 import { createServer } from "node:http";
 import { createGunzip, createInflate } from "node:zlib";
 import { promisify } from "node:util";
@@ -919,6 +921,26 @@ function createStderrLogger(prefix) {
 
 //#endregion
 //#region packages/core/dist/dispatch/dispatcher-impl.js
+const WORKTREE_COUPLED_TASK_TYPES = new Set([
+	"create-story",
+	"dev-story",
+	"code-review",
+	"minor-fixes",
+	"major-rework",
+	"build-fix",
+	"test-plan",
+	"test-expansion",
+	"probe-author"
+]);
+const GIT_STATE_ENV_KEYS = [
+	"PWD",
+	"OLDPWD",
+	"INIT_CWD",
+	"GIT_DIR",
+	"GIT_WORK_TREE",
+	"GIT_INDEX_FILE",
+	"GIT_COMMON_DIR"
+];
 const SHUTDOWN_GRACE_MS = 1e4;
 const SHUTDOWN_MAX_WAIT_MS = 3e4;
 const CHARS_PER_TOKEN$3 = 4;
@@ -1242,6 +1264,29 @@ var DispatcherImpl = class {
 			});
 			return;
 		}
+		if (workingDirectory === void 0 && WORKTREE_COUPLED_TASK_TYPES.has(taskType)) {
+			this._logger.error({
+				id,
+				agent,
+				taskType
+			}, "dispatch rejected: workingDirectory is required for worktree-coupled task types (H4.1)");
+			this._running.delete(id);
+			this._drainQueue();
+			resolve$2({
+				id,
+				status: "failed",
+				exitCode: -1,
+				output: "",
+				parsed: null,
+				parseError: `workingDirectory is required for taskType "${taskType}" — coding-pipeline dispatches must name their worktree explicitly (H4.1 AC2)`,
+				durationMs: 0,
+				tokenEstimate: {
+					input: Math.ceil(prompt.length / CHARS_PER_TOKEN$3),
+					output: 0
+				}
+			});
+			return;
+		}
 		const worktreePath = workingDirectory ?? process.cwd();
 		const resolvedMaxTurns = maxTurns ?? DEFAULT_MAX_TURNS[taskType];
 		const capabilities = adapter.getCapabilities();
@@ -1265,6 +1310,8 @@ var DispatcherImpl = class {
 		const env = { ...process.env };
 		const parentNodeOpts = env["NODE_OPTIONS"] ?? "";
 		if (!parentNodeOpts.includes("--max-old-space-size")) env["NODE_OPTIONS"] = `${parentNodeOpts} --max-old-space-size=512`.trim();
+		for (const key of GIT_STATE_ENV_KEYS) delete env[key];
+		env["GIT_CEILING_DIRECTORIES"] = dirname$1(worktreePath);
 		if (cmd.env !== void 0) Object.assign(env, cmd.env);
 		if (cmd.unsetEnvKeys !== void 0) for (const key of cmd.unsetEnvKeys) delete env[key];
 		const proc = spawn(cmd.binary, cmd.args, {
@@ -6233,7 +6280,10 @@ const TelemetryConfigSchema = z.object({
 	meshUrl: z.string().url().optional(),
 	projectId: z.string().optional()
 }).strict();
-const WorktreeConfigSchema = z.object({ copy_files: z.array(z.string()).default([]) }).strict();
+const WorktreeConfigSchema = z.object({
+	copy_files: z.array(z.string()).default([]),
+	base: z.enum(["in-repo", "external"]).optional()
+}).strict();
 /** Current supported config format version */
 const CURRENT_CONFIG_FORMAT_VERSION = "1";
 /** Current supported task graph version */
@@ -6252,11 +6302,15 @@ const SubstrateConfigSchema = z.object({
 	telemetry: TelemetryConfigSchema.optional(),
 	worktree: WorktreeConfigSchema.optional(),
 	trivialOutputThreshold: z.number().int().nonnegative().optional(),
-	finalization: z.object({ mode: z.enum([
-		"merge",
-		"branch",
-		"pr"
-	]).optional() }).strict().optional()
+	finalization: z.object({
+		mode: z.enum([
+			"merge",
+			"branch",
+			"pr"
+		]).optional(),
+		merge_strategy: z.enum(["ff-only", "three-way"]).optional(),
+		epic_gate_command: z.string().optional()
+	}).strict().optional()
 }).passthrough();
 const PartialProviderConfigSchema = ProviderConfigSchema.partial();
 const PartialGlobalSettingsSchema = GlobalSettingsSchema.partial();
@@ -6274,11 +6328,15 @@ const PartialSubstrateConfigSchema = z.object({
 	telemetry: TelemetryConfigSchema.partial().optional(),
 	worktree: WorktreeConfigSchema.partial().optional(),
 	trivialOutputThreshold: z.number().int().nonnegative().optional(),
-	finalization: z.object({ mode: z.enum([
-		"merge",
-		"branch",
-		"pr"
-	]).optional() }).strict().optional()
+	finalization: z.object({
+		mode: z.enum([
+			"merge",
+			"branch",
+			"pr"
+		]).optional(),
+		merge_strategy: z.enum(["ff-only", "three-way"]).optional(),
+		epic_gate_command: z.string().optional()
+	}).strict().optional()
 }).passthrough();
 
 //#endregion
@@ -6610,8 +6668,8 @@ function readEnvOverrides(logger) {
 /**
 * Get a value from a nested object using dot-notation key.
 */
-function getByPath(obj, path$1) {
-	const parts = path$1.split(".");
+function getByPath(obj, path$3) {
+	const parts = path$3.split(".");
 	let cursor = obj;
 	for (const part of parts) {
 		if (cursor === null || cursor === void 0 || typeof cursor !== "object") return void 0;
@@ -6623,8 +6681,8 @@ function getByPath(obj, path$1) {
 * Return a deep clone of `obj` with `path` set to `value`.
 * Creates intermediate objects as needed.
 */
-function setByPath(obj, path$1, value) {
-	const parts = path$1.split(".");
+function setByPath(obj, path$3, value) {
+	const parts = path$3.split(".");
 	const result = { ...obj };
 	let cursor = result;
 	for (let i = 0; i < parts.length - 1; i++) {
@@ -6646,7 +6704,7 @@ var ConfigSystemImpl = class {
 	_logger;
 	constructor(options = {}) {
 		this._projectConfigDir = options.projectConfigDir ? resolve(options.projectConfigDir) : resolve(process.cwd(), ".substrate");
-		this._globalConfigDir = options.globalConfigDir ? resolve(options.globalConfigDir) : resolve(homedir(), ".substrate");
+		this._globalConfigDir = options.globalConfigDir ? resolve(options.globalConfigDir) : resolve(homedir$1(), ".substrate");
 		this._cliOverrides = options.cliOverrides ?? {};
 		this._logger = options.logger ?? createStderrLogger("config-system");
 	}
@@ -10771,6 +10829,833 @@ const CompileResultSchema = z.object({
 	truncated: z.boolean()
 });
 
+//#endregion
+//#region packages/core/dist/git/git-utils.js
+const MIN_GIT_MAJOR = 2;
+const MIN_GIT_MINOR = 20;
+/**
+* Spawn a git subprocess with the given args.
+*
+* @param args    - Arguments to pass to git (e.g., ['worktree', 'add', ...])
+* @param options - Optional spawn options (cwd, env)
+* @returns       - Object with stdout, stderr, and exit code
+*/
+function spawnGit(args, options) {
+	return new Promise((resolve$2) => {
+		const proc = spawn("git", args, {
+			cwd: options?.cwd,
+			env: options?.env ?? process.env,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		let stdout = "";
+		let stderr = "";
+		proc.stdout?.on("data", (chunk) => {
+			stdout += chunk.toString();
+		});
+		proc.stderr?.on("data", (chunk) => {
+			stderr += chunk.toString();
+		});
+		proc.on("close", (code) => {
+			resolve$2({
+				stdout: stdout.trim(),
+				stderr: stderr.trim(),
+				code: code ?? 1
+			});
+		});
+		proc.on("error", (err) => {
+			resolve$2({
+				stdout: "",
+				stderr: err.message,
+				code: 1
+			});
+		});
+	});
+}
+/**
+* Get the installed git version string.
+*
+* @returns Version string like "2.42.0"
+* @throws  Error if git is not installed or version cannot be parsed
+*/
+async function getGitVersion() {
+	const result = await spawnGit(["--version"]);
+	if (result.code !== 0) throw new Error(`git --version failed: ${result.stderr}`);
+	const match = /git version\s+(\d+\.\d+(?:\.\d+)?)/.exec(result.stdout);
+	if (match === null || match[1] === void 0) throw new Error(`Unable to parse git version from output: "${result.stdout}"`);
+	return match[1];
+}
+/**
+* Parse a git version string into major/minor/patch components.
+*
+* @param versionString - Version string like "2.42.0" or "2.20"
+* @returns             - Parsed version components
+*/
+function parseGitVersion(versionString) {
+	const parts = versionString.split(".").map(Number);
+	return {
+		major: parts[0] ?? 0,
+		minor: parts[1] ?? 0,
+		patch: parts[2] ?? 0
+	};
+}
+/**
+* Check if the given git version string is >= 2.20.0.
+*
+* @param version - Version string like "2.42.0"
+* @returns       - true if version >= 2.20.0
+*/
+function isGitVersionSupported(version) {
+	const { major, minor } = parseGitVersion(version);
+	if (major > MIN_GIT_MAJOR) return true;
+	if (major === MIN_GIT_MAJOR && minor >= MIN_GIT_MINOR) return true;
+	return false;
+}
+/**
+* Verify that git is installed and version >= 2.20.
+*
+* @throws Error with clear message if git is not installed or too old
+*/
+async function verifyGitVersion() {
+	let version;
+	try {
+		version = await getGitVersion();
+	} catch (err) {
+		throw new Error(`git is not installed or could not be executed. Please install git 2.20 or newer. Details: ${String(err)}`);
+	}
+	if (!isGitVersionSupported(version)) {
+		const { major, minor, patch } = parseGitVersion(version);
+		throw new Error(`Git version ${major}.${minor}.${patch} is too old. Substrate requires git 2.20 or newer. Please upgrade git: https://git-scm.com/downloads`);
+	}
+}
+/**
+* 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.
+*
+* 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 };
+}
+/**
+* Decide whether removing a story worktree AND deleting its branch is safe
+* (H0.3, field findings #17/#19). Unsafe when:
+*   - the worktree has uncommitted changes (removal destroys the only copy), or
+*   - the branch carries commits not reachable from the project's current HEAD
+*     (branch -D destroys them — this is where H0.1's wip checkpoints live), or
+*   - either state could not be determined (negative unmergedCommits).
+*
+* Pure + exported for testing (mirrors decideWorktreeReclaim; the git I/O that
+* produces the inputs lives in inspectWorktreeRemovalSafety).
+*/
+function decideWorktreeRemoval(hasUncommittedChanges, uncommittedFiles, unmergedCommits, branchName) {
+	const reasons = [];
+	if (hasUncommittedChanges) {
+		const preview = uncommittedFiles.slice(0, 10).join(", ");
+		const more = uncommittedFiles.length > 10 ? ` (+${String(uncommittedFiles.length - 10)} more)` : "";
+		reasons.push(`the worktree has ${String(uncommittedFiles.length)} uncommitted change(s) that removal would destroy` + (preview.length > 0 ? `: ${preview}${more}` : ""));
+	}
+	if (unmergedCommits > 0) reasons.push(`branch ${branchName} carries ${String(unmergedCommits)} commit(s) not reachable from the current HEAD — deleting the branch would destroy them`);
+	if (unmergedCommits < 0) reasons.push("the branch state could not be verified as safe to discard");
+	return {
+		safe: reasons.length === 0,
+		reasons
+	};
+}
+/**
+* Gather the inputs for `decideWorktreeRemoval` from git. Thin I/O wrapper:
+*   - `git status --porcelain` inside the worktree (skipped when the directory
+*     is missing — nothing on disk to lose)
+*   - `git rev-list --count HEAD..<branch>` in the project root (commits the
+*     branch has that the current checkout does not; 0 when the branch is
+*     merged or absent, -1 when the count could not be determined)
+*/
+async function inspectWorktreeRemovalSafety(worktreePath, projectRoot, branchName) {
+	let hasUncommittedChanges = false;
+	let uncommittedFiles = [];
+	const worktreeOnDisk = await access$1(worktreePath).then(() => true).catch(() => false);
+	if (worktreeOnDisk) {
+		const statusResult = await spawnGit(["status", "--porcelain"], { cwd: worktreePath });
+		if (statusResult.code === 0) {
+			uncommittedFiles = statusResult.stdout.split("\n").filter((line) => line.trim().length > 0).map((line) => line.slice(3).trim());
+			hasUncommittedChanges = uncommittedFiles.length > 0;
+		} else return decideWorktreeRemoval(false, [], -1, branchName);
+	}
+	const branchExists = (await spawnGit([
+		"rev-parse",
+		"--verify",
+		branchName
+	], { cwd: projectRoot })).code === 0;
+	let unmergedCommits = 0;
+	if (branchExists) {
+		const aheadResult = await spawnGit([
+			"rev-list",
+			"--count",
+			`HEAD..${branchName}`
+		], { cwd: projectRoot });
+		unmergedCommits = aheadResult.code === 0 ? Number.parseInt(aheadResult.stdout.trim(), 10) || 0 : -1;
+	}
+	return decideWorktreeRemoval(hasUncommittedChanges, uncommittedFiles, unmergedCommits, branchName);
+}
+async function createWorktree(projectRoot, taskId, branchName, baseBranch, copyFiles = [], baseDirectory = ".substrate-worktrees") {
+	const worktreePath = path$2.resolve(projectRoot, baseDirectory, taskId);
+	await mkdir$1(path$2.dirname(worktreePath), { recursive: true });
+	const worktreeExists = await access$1(worktreePath).then(() => true).catch((err) => {
+		if (err.code === "ENOENT") return false;
+		throw err;
+	});
+	if (worktreeExists) {
+		const listResult = await spawnGit([
+			"worktree",
+			"list",
+			"--porcelain"
+		], { cwd: projectRoot });
+		const registeredPaths = listResult.stdout.split("\n").filter((line) => line.startsWith("worktree ")).map((line) => line.slice(9).trim());
+		const isRegistered = registeredPaths.includes(worktreePath);
+		if (!isRegistered) await rm(worktreePath, {
+			recursive: true,
+			force: true
+		});
+		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",
+		"add",
+		worktreePath,
+		"-b",
+		branchName,
+		baseBranch
+	], { cwd: projectRoot });
+	if (addResult.code !== 0) throw new Error(`git worktree add failed for task "${taskId}": ${addResult.stderr || addResult.stdout}`);
+	await copyFilesToWorktree(projectRoot, worktreePath, copyFiles);
+	return { worktreePath };
+}
+/**
+* Copy files from a source directory into a target worktree.
+*
+* Skips missing files silently (intentional — config like `[".env",
+* ".env.local"]` should not blow up if `.env.local` doesn't exist in the
+* parent checkout). Creates parent directories for nested paths.
+*
+* Exported for testability; not part of the public worktree API.
+*/
+async function copyFilesToWorktree(sourceRoot, worktreePath, files) {
+	if (files.length === 0) return;
+	for (const relativePath of files) {
+		if (path$2.isAbsolute(relativePath) || relativePath.split(path$2.sep).includes("..")) continue;
+		const sourcePath = path$2.join(sourceRoot, relativePath);
+		const destPath = path$2.join(worktreePath, relativePath);
+		try {
+			await access$1(sourcePath);
+		} catch {
+			continue;
+		}
+		const destDir = path$2.dirname(destPath);
+		if (destDir !== worktreePath) await mkdir$1(destDir, { recursive: true });
+		await copyFile(sourcePath, destPath);
+	}
+}
+/**
+* Remove a git worktree by path.
+*
+* Uses `git worktree remove --force` to handle unclean worktrees.
+*
+* @param worktreePath - Absolute path to the worktree directory
+* @param projectRoot  - Absolute path to the git repository root
+* @throws             - Error if git command fails
+*/
+async function removeWorktree(worktreePath, projectRoot) {
+	const spawnOpts = {};
+	if (projectRoot !== void 0) spawnOpts.cwd = projectRoot;
+	const result = await spawnGit([
+		"worktree",
+		"remove",
+		"--force",
+		worktreePath
+	], spawnOpts);
+	if (result.code !== 0) throw new Error(`git worktree remove failed for "${worktreePath}": ${result.stderr || result.stdout}`);
+}
+/**
+* Delete a git branch using `git branch -D`.
+*
+* @param branchName  - Branch name to delete (e.g., "substrate/story-abc123")
+* @param projectRoot - Absolute path to the git repository root
+* @returns           - true if branch was successfully deleted, false otherwise
+*/
+async function removeBranch(branchName, projectRoot) {
+	const spawnOpts = {};
+	if (projectRoot !== void 0) spawnOpts.cwd = projectRoot;
+	const result = await spawnGit([
+		"branch",
+		"-D",
+		branchName
+	], spawnOpts);
+	if (result.code !== 0) return false;
+	return true;
+}
+/**
+* Scan the worktrees base directory and return paths of all found worktree directories.
+*
+* @param projectRoot   - Absolute path to the git repository root
+* @param baseDirectory - Relative directory name for worktrees (default: '.substrate-worktrees')
+* @returns             - Array of absolute worktree directory paths
+*/
+async function getOrphanedWorktrees(projectRoot, baseDirectory = ".substrate-worktrees") {
+	const worktreesDir = path$2.resolve(projectRoot, baseDirectory);
+	try {
+		await access$1(worktreesDir);
+	} catch {
+		return [];
+	}
+	let entries;
+	try {
+		entries = await readdir$1(worktreesDir, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	return entries.filter((entry) => entry.isDirectory()).map((entry) => path$2.join(worktreesDir, entry.name));
+}
+/**
+* Simulate a merge using git merge --no-commit --no-ff without committing.
+*
+* This runs in the target branch's working directory (the project root or
+* worktree path). The simulation must be aborted after checking conflicts
+* via abortMerge().
+*
+* @param branchName  - The source branch to simulate merging
+* @param cwd         - Working directory (must be on the target branch)
+* @returns           - true if merge would be clean, false if there are conflicts
+*/
+async function simulateMerge(branchName, cwd) {
+	const result = await spawnGit([
+		"merge",
+		"--no-commit",
+		"--no-ff",
+		branchName
+	], { cwd });
+	if (result.code === 0) return true;
+	return false;
+}
+/**
+* Abort a merge in progress using git merge --abort.
+*
+* Should be called after simulateMerge() to clean up the merge state,
+* regardless of whether conflicts were found.
+*
+* @param cwd - Working directory (same as used for simulateMerge)
+*/
+async function abortMerge(cwd) {
+	await spawnGit(["merge", "--abort"], { cwd });
+}
+/**
+* Get a list of files with conflicts during a merge.
+*
+* Must be called while a merge is in progress (after simulateMerge() and
+* before abortMerge()).
+*
+* @param cwd - Working directory of the repository
+* @returns   - Array of conflicting file paths
+*/
+async function getConflictingFiles(cwd) {
+	const result = await spawnGit([
+		"diff",
+		"--name-only",
+		"--diff-filter=U"
+	], { cwd });
+	if (result.code !== 0) return [];
+	if (result.stdout.trim() === "") return [];
+	return result.stdout.trim().split("\n").filter((f) => f.trim().length > 0);
+}
+/**
+* Perform an actual merge using git merge --no-ff.
+*
+* Should only be called after detectConflicts() confirms there are no conflicts.
+* Creates a merge commit even if fast-forward is possible (--no-ff ensures history).
+*
+* @param branchName  - The source branch to merge
+* @param cwd         - Working directory (must be on the target branch)
+* @returns           - true if merge succeeded, false otherwise
+*/
+async function performMerge(branchName, cwd) {
+	const result = await spawnGit([
+		"merge",
+		"--no-ff",
+		branchName
+	], { cwd });
+	if (result.code !== 0) return false;
+	return true;
+}
+/**
+* Get a list of files changed in the most recent merge.
+*
+* Uses git diff --name-only HEAD~1..HEAD to find files in the merge commit.
+* Falls back to empty array if commit history is insufficient.
+*
+* @param cwd - Working directory of the repository
+* @returns   - Array of file paths that were merged
+*/
+async function getMergedFiles(cwd) {
+	const result = await spawnGit([
+		"diff",
+		"--name-only",
+		"HEAD~1..HEAD"
+	], { cwd });
+	if (result.code !== 0) {
+		const altResult = await spawnGit([
+			"show",
+			"--name-only",
+			"--format=",
+			"HEAD"
+		], { cwd });
+		if (altResult.code !== 0) return [];
+		return altResult.stdout.trim().split("\n").filter((f) => f.trim().length > 0);
+	}
+	if (result.stdout.trim() === "") return [];
+	return result.stdout.trim().split("\n").filter((f) => f.trim().length > 0);
+}
+
+//#endregion
+//#region packages/core/dist/git/git-worktree-manager-impl.js
+/**
+* Branch name prefix for substrate per-story branches.
+*
+* Exported as the canonical source of truth so consumers (orchestrator,
+* integration tests, tooling) can compose branch names without
+* independently encoding the prefix. v0.20.82 production bug:
+* `orchestrator-impl.ts:4290` hardcoded `substrate/story-${storyKey}`
+* while this module created `substrate/task-${taskId}` — the resulting
+* merge-to-main looked at a non-existent branch. Recurrence prevention:
+* all branch-name construction MUST import this constant.
+*/
+const BRANCH_PREFIX = "substrate/story-";
+const DEFAULT_WORKTREE_BASE = ".substrate-worktrees";
+/**
+* H4.2 (AC2): resolve the worktree base directory for a project.
+*
+* 'external' (the NEW DEFAULT) puts worktrees OUTSIDE the parent tree at
+* `~/.substrate/worktrees/<projectname>-<hash8>/` — an agent inside its
+* worktree has no parent repo above it to leak into (composes with H4.1's
+* GIT_CEILING_DIRECTORIES, which points at this base). 'in-repo' retains the
+* pre-H4.2 `<projectRoot>/.substrate-worktrees/` for tooling that assumed
+* the old path (MIGRATION NOTE: reconcile-from-disk, editor bookmarks, and
+* scripts that globbed `.substrate-worktrees/` should use
+* `substrate worktrees list` or set `worktree.base: in-repo`).
+*
+* When `baseOverride` is not given, reads `worktree.base` from
+* `.substrate/config.yaml` directly (same no-threading pattern as
+* `resolveEpicsPathOverride`) so EVERY construction site — orchestrator,
+* `substrate merge`, `substrate worktrees` — resolves identically.
+*/
+function resolveWorktreeBaseDirectory(projectRoot, baseOverride) {
+	let mode = baseOverride;
+	if (mode === void 0) try {
+		const raw = readFileSync(path$1.join(projectRoot, ".substrate", "config.yaml"), "utf-8");
+		const parsed = yaml.load(raw);
+		if (parsed?.worktree?.base === "in-repo" || parsed?.worktree?.base === "external") mode = parsed.worktree.base;
+	} catch {}
+	if ((mode ?? "external") === "in-repo") return DEFAULT_WORKTREE_BASE;
+	const hash = createHash("sha256").update(path$1.resolve(projectRoot)).digest("hex").slice(0, 8);
+	return path$1.join(homedir(), ".substrate", "worktrees", `${path$1.basename(projectRoot)}-${hash}`);
+}
+var GitWorktreeManagerImpl = class {
+	_eventBus;
+	_projectRoot;
+	_baseDirectory;
+	_db;
+	_logger;
+	/** v0.20.109: files to copy from project root into each new worktree (e.g. `.env`). */
+	_copyFiles;
+	/** Bound listener references for cleanup in shutdown() */
+	_onTaskReady;
+	_onTaskComplete;
+	_onTaskFailed;
+	constructor(eventBus, projectRoot, baseDirectory = DEFAULT_WORKTREE_BASE, db = null, logger, copyFiles = []) {
+		this._eventBus = eventBus;
+		this._projectRoot = projectRoot;
+		this._baseDirectory = baseDirectory;
+		this._db = db;
+		this._logger = logger ?? createStderrLogger("git-worktree-manager");
+		this._copyFiles = copyFiles;
+		this._onTaskReady = ({ taskId }) => {
+			this._handleTaskReady(taskId).catch((err) => {
+				this._logger.error({
+					taskId,
+					err
+				}, "Unhandled error in _handleTaskReady");
+			});
+		};
+		this._onTaskComplete = ({ taskId }) => {
+			this._handleTaskDone(taskId);
+		};
+		this._onTaskFailed = ({ taskId }) => {
+			this._handleTaskDone(taskId);
+		};
+	}
+	async initialize() {
+		this._logger.info({ projectRoot: this._projectRoot }, "GitWorktreeManager.initialize()");
+		await this.verifyGitVersion();
+		const cleaned = await this.cleanupAllWorktrees();
+		if (cleaned > 0) this._logger.info({ cleaned }, "Recovered orphaned worktrees on startup");
+		this._eventBus.on("task:ready", this._onTaskReady);
+		this._eventBus.on("task:complete", this._onTaskComplete);
+		this._eventBus.on("task:failed", this._onTaskFailed);
+		this._logger.info("GitWorktreeManager initialized");
+	}
+	async shutdown() {
+		this._logger.info("GitWorktreeManager.shutdown()");
+		this._eventBus.off("task:ready", this._onTaskReady);
+		this._eventBus.off("task:complete", this._onTaskComplete);
+		this._eventBus.off("task:failed", this._onTaskFailed);
+		await this.cleanupAllWorktrees();
+		this._logger.info("GitWorktreeManager shutdown complete");
+	}
+	async _handleTaskReady(taskId) {
+		this._logger.debug({ taskId }, "task:ready — creating worktree");
+		try {
+			await this.createWorktree(taskId);
+		} catch (err) {
+			this._logger.error({
+				taskId,
+				err
+			}, "Failed to create worktree for task");
+		}
+	}
+	async _handleTaskDone(taskId) {
+		this._logger.debug({ taskId }, "task done — cleaning up worktree");
+		try {
+			await this.cleanupWorktree(taskId);
+		} catch (err) {
+			this._logger.warn({
+				taskId,
+				err
+			}, "Failed to cleanup worktree for task");
+		}
+	}
+	async createWorktree(taskId, baseBranch) {
+		if (!taskId || taskId.trim().length === 0) throw new Error("createWorktree: taskId must be a non-empty string");
+		const resolvedBaseBranch = baseBranch ?? await this._detectCurrentBranch() ?? "main";
+		const branchName = BRANCH_PREFIX + taskId;
+		const worktreePath = this.getWorktreePath(taskId);
+		this._logger.debug({
+			taskId,
+			branchName,
+			worktreePath,
+			baseBranch: resolvedBaseBranch,
+			copyFiles: this._copyFiles
+		}, "createWorktree");
+		const copyFiles = this._copyFiles.includes(".substrate/project-profile.yaml") ? this._copyFiles : [...this._copyFiles, ".substrate/project-profile.yaml"];
+		await createWorktree(this._projectRoot, taskId, branchName, resolvedBaseBranch, copyFiles, this._baseDirectory);
+		const createdAt = new Date();
+		this._eventBus.emit("worktree:created", {
+			taskId,
+			branchName,
+			worktreePath,
+			createdAt
+		});
+		const info = {
+			taskId,
+			branchName,
+			worktreePath,
+			createdAt
+		};
+		this._logger.info({
+			taskId,
+			branchName,
+			worktreePath
+		}, "Worktree created");
+		return info;
+	}
+	async cleanupWorktree(taskId, opts) {
+		const branchName = BRANCH_PREFIX + taskId;
+		const worktreePath = this.getWorktreePath(taskId);
+		this._logger.debug({
+			taskId,
+			branchName,
+			worktreePath,
+			force: opts?.force === true
+		}, "cleanupWorktree");
+		if (opts?.force !== true) {
+			const decision = await inspectWorktreeRemovalSafety(worktreePath, this._projectRoot, branchName);
+			const blockingReasons = opts?.keepBranch === true ? decision.reasons.filter((r) => r.includes("uncommitted")) : decision.reasons;
+			if (blockingReasons.length > 0) throw new Error(`refusing to clean up worktree for "${taskId}": ${blockingReasons.join("; ")}.\nInspect first (git -C ${worktreePath} status; git log ${branchName} --oneline) or re-run with --force to discard.`);
+		}
+		let worktreeExists = false;
+		try {
+			await access$1(worktreePath);
+			worktreeExists = true;
+		} catch {
+			this._logger.debug({
+				taskId,
+				worktreePath
+			}, "cleanupWorktree: worktree does not exist, skipping removal");
+		}
+		if (worktreeExists) try {
+			await removeWorktree(worktreePath, this._projectRoot);
+		} catch (err) {
+			this._logger.warn({
+				taskId,
+				worktreePath,
+				err
+			}, "removeWorktree failed during cleanup");
+		}
+		if (opts?.keepBranch !== true) try {
+			await removeBranch(branchName, this._projectRoot);
+		} catch (err) {
+			this._logger.warn({
+				taskId,
+				branchName,
+				err
+			}, "removeBranch failed during cleanup");
+		}
+		this._eventBus.emit("worktree:removed", {
+			taskId,
+			branchName
+		});
+		this._logger.info({
+			taskId,
+			branchName
+		}, "Worktree cleaned up");
+	}
+	async cleanupAllWorktrees(opts) {
+		this._logger.debug({
+			projectRoot: this._projectRoot,
+			force: opts?.force === true
+		}, "cleanupAllWorktrees");
+		const orphanedPaths = await getOrphanedWorktrees(this._projectRoot, this._baseDirectory);
+		let cleaned = 0;
+		for (const worktreePath of orphanedPaths) {
+			const taskId = path$1.basename(worktreePath);
+			const branchGuardName = BRANCH_PREFIX + taskId;
+			const decision = opts?.force === true ? {
+				safe: true,
+				reasons: []
+			} : await inspectWorktreeRemovalSafety(worktreePath, this._projectRoot, branchGuardName);
+			if (!decision.safe) {
+				this._logger.warn({
+					taskId,
+					worktreePath,
+					reasons: decision.reasons
+				}, "cleanupAllWorktrees: preserving worktree — removal would destroy work (use `substrate worktrees cleanup --force` to discard)");
+				continue;
+			}
+			let worktreeRemoved = false;
+			try {
+				await removeWorktree(worktreePath, this._projectRoot);
+				worktreeRemoved = true;
+				this._logger.debug({
+					taskId,
+					worktreePath
+				}, "cleanupAllWorktrees: removed orphaned worktree");
+			} catch (err) {
+				this._logger.warn({
+					taskId,
+					worktreePath,
+					err
+				}, "cleanupAllWorktrees: failed to remove worktree");
+			}
+			const branchName = BRANCH_PREFIX + taskId;
+			try {
+				const branchRemoved = await removeBranch(branchName, this._projectRoot);
+				if (branchRemoved) this._logger.debug({
+					taskId,
+					branchName
+				}, "cleanupAllWorktrees: removed orphaned branch");
+			} catch (err) {
+				this._logger.warn({
+					taskId,
+					branchName,
+					err
+				}, "cleanupAllWorktrees: failed to remove branch");
+			}
+			if (worktreeRemoved) cleaned++;
+		}
+		if (cleaned > 0) this._logger.info({ cleaned }, "cleanupAllWorktrees: recovered orphaned worktrees");
+		return cleaned;
+	}
+	async detectConflicts(taskId, targetBranch = "main") {
+		if (!taskId || taskId.trim().length === 0) throw new Error("detectConflicts: taskId must be a non-empty string");
+		const branchName = BRANCH_PREFIX + taskId;
+		const worktreePath = this.getWorktreePath(taskId);
+		this._logger.debug({
+			taskId,
+			branchName,
+			targetBranch
+		}, "detectConflicts");
+		try {
+			await access$1(worktreePath);
+		} catch {
+			throw new Error(`detectConflicts: Worktree for task "${taskId}" not found at "${worktreePath}". The worktree may have already been cleaned up.`);
+		}
+		const mergeClean = await simulateMerge(branchName, this._projectRoot);
+		let conflictingFiles = [];
+		try {
+			if (!mergeClean) conflictingFiles = await getConflictingFiles(this._projectRoot);
+		} finally {
+			await abortMerge(this._projectRoot);
+		}
+		const report = {
+			hasConflicts: !mergeClean || conflictingFiles.length > 0,
+			conflictingFiles,
+			taskId,
+			targetBranch
+		};
+		if (report.hasConflicts) this._eventBus.emit("worktree:conflict", {
+			taskId,
+			branch: branchName,
+			conflictingFiles: report.conflictingFiles
+		});
+		this._logger.info({
+			taskId,
+			hasConflicts: report.hasConflicts,
+			conflictCount: conflictingFiles.length
+		}, "Conflict detection complete");
+		return report;
+	}
+	async mergeWorktree(taskId, targetBranch = "main") {
+		if (!taskId || taskId.trim().length === 0) throw new Error("mergeWorktree: taskId must be a non-empty string");
+		const branchName = BRANCH_PREFIX + taskId;
+		this._logger.debug({
+			taskId,
+			branchName,
+			targetBranch
+		}, "mergeWorktree");
+		const conflictReport = await this.detectConflicts(taskId, targetBranch);
+		if (conflictReport.hasConflicts) {
+			this._logger.info({
+				taskId,
+				conflictCount: conflictReport.conflictingFiles.length
+			}, "Merge skipped due to conflicts");
+			return {
+				success: false,
+				mergedFiles: [],
+				conflicts: conflictReport
+			};
+		}
+		const mergeSuccess = await performMerge(branchName, this._projectRoot);
+		if (!mergeSuccess) throw new Error(`mergeWorktree: git merge --no-ff failed for task "${taskId}" branch "${branchName}"`);
+		const mergedFiles = await getMergedFiles(this._projectRoot);
+		this._eventBus.emit("worktree:merged", {
+			taskId,
+			branch: branchName,
+			mergedFiles
+		});
+		const result = {
+			success: true,
+			mergedFiles
+		};
+		this._logger.info({
+			taskId,
+			branchName,
+			mergedFileCount: mergedFiles.length
+		}, "Worktree merged successfully");
+		return result;
+	}
+	async listWorktrees() {
+		this._logger.debug({
+			projectRoot: this._projectRoot,
+			baseDirectory: this._baseDirectory
+		}, "listWorktrees");
+		const worktreePaths = await getOrphanedWorktrees(this._projectRoot, this._baseDirectory);
+		const results = [];
+		for (const worktreePath of worktreePaths) {
+			const taskId = path$1.basename(worktreePath);
+			const branchName = BRANCH_PREFIX + taskId;
+			let createdAt;
+			try {
+				const { stat: stat$2 } = await import("node:fs/promises");
+				const stats = await stat$2(worktreePath);
+				createdAt = stats.birthtime ?? stats.ctime;
+			} catch {
+				createdAt = new Date();
+			}
+			results.push({
+				taskId,
+				branchName,
+				worktreePath,
+				createdAt
+			});
+		}
+		this._logger.debug({ count: results.length }, "listWorktrees: found worktrees");
+		return results;
+	}
+	/** H4.2: current branch of the parent repo (undefined when detached/unreadable). */
+	async _detectCurrentBranch() {
+		try {
+			const result = await spawnGit([
+				"rev-parse",
+				"--abbrev-ref",
+				"HEAD"
+			], { cwd: this._projectRoot });
+			const name = result.code === 0 ? result.stdout.trim() : "";
+			return name !== "" && name !== "HEAD" ? name : void 0;
+		} catch {
+			return void 0;
+		}
+	}
+	getWorktreePath(taskId) {
+		return path$1.resolve(this._projectRoot, this._baseDirectory, taskId);
+	}
+	async verifyGitVersion() {
+		try {
+			await verifyGitVersion();
+		} catch (err) {
+			throw new Error(`GitWorktreeManager: git version check failed: ${String(err)}`);
+		}
+	}
+};
+function createGitWorktreeManager(options) {
+	return new GitWorktreeManagerImpl(
+		options.eventBus,
+		options.projectRoot,
+		// H4.2: single resolution point — explicit option, else `worktree.base`
+		// from .substrate/config.yaml, else the external default.
+		options.baseDirectory ?? resolveWorktreeBaseDirectory(options.projectRoot),
+		options.db ?? null,
+		options.logger,
+		options.copyFiles
+);
+}
+
 //#endregion
 //#region packages/core/dist/version-manager/update-checker.js
 /**
@@ -11089,9 +11974,9 @@ var VersionManagerImpl = class {
 		try {
 			const _require = createRequire(import.meta.url);
 			const fs = _require("fs");
-			const path$1 = _require("path");
+			const path$3 = _require("path");
 			const yaml$1 = _require("js-yaml");
-			const configPath = path$1.join(process.cwd(), ".substrate", "config.yaml");
+			const configPath = path$3.join(process.cwd(), ".substrate", "config.yaml");
 			try {
 				const raw = fs.readFileSync(configPath, "utf-8");
 				configObj = yaml$1.load(raw) ?? {};
@@ -11333,7 +12218,7 @@ function createExperimenter(config, deps) {
 		], { cwd: config.projectRoot });
 		return result.stdout.trim();
 	}
-	async function createWorktree(worktreePath, branchName) {
+	async function createWorktree$1(worktreePath, branchName) {
 		const result = await git([
 			"worktree",
 			"add",
@@ -11343,7 +12228,7 @@ function createExperimenter(config, deps) {
 		], { cwd: config.projectRoot });
 		if (result.code !== 0) throw new Error(`Failed to create worktree ${worktreePath}: ${result.stderr}`);
 	}
-	async function removeWorktree(worktreePath) {
+	async function removeWorktree$1(worktreePath) {
 		const result = await git([
 			"worktree",
 			"remove",
@@ -11453,7 +12338,7 @@ function createExperimenter(config, deps) {
 		try {
 			currentPhase = "BRANCHING";
 			log(`[experimenter] Creating worktree: ${worktreePath} on branch ${branchName}`);
-			await createWorktree(worktreePath, branchName);
+			await createWorktree$1(worktreePath, branchName);
 			worktreeCreated = true;
 			currentPhase = "MODIFYING";
 			const promptFile = resolvePromptFile(rec, worktreePath, config.pack);
@@ -11496,7 +12381,7 @@ function createExperimenter(config, deps) {
 			log(`[experimenter] Error in phase ${currentPhase}: ${caughtError}`);
 		} finally {
 			if (worktreeCreated) try {
-				await removeWorktree(worktreePath);
+				await removeWorktree$1(worktreePath);
 			} catch {
 				log(`[experimenter] Warning: could not remove worktree ${worktreePath}`);
 			}
@@ -11645,5 +12530,5 @@ async function callLLM(params) {
 }
 
 //#endregion
-export { ADVISORY_NOTES, AdapterRegistry, AdtError, BudgetConfigSchema, CLAUDE_AUTH_FAILURE_HINT, 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, detectClaudeAuthFailure, 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-DT378h1M.js.map
+export { ADVISORY_NOTES, AdapterRegistry, AdtError, BRANCH_PREFIX, BudgetConfigSchema, CLAUDE_AUTH_FAILURE_HINT, 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, createGitWorktreeManager, createPipelineRun, createRequirement, createStderrLogger, createVersionManager, detectClaudeAuthFailure, 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-C2CAZDep.js.map