@try-works/dsh-recursive-mode 0.1.18 → 0.2.0

package/lib/index.js

@@ -6,6 +6,154 @@ import { createHash } from "node:crypto";
 import { execFileSync } from "node:child_process";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 import { fileURLToPath } from "node:url";
+//#region src/git-context.ts
+/**
+* git-context.ts — live git facts used for worktree + branch awareness (R?).
+*
+* Worktree/branch awareness goal: the plugin must know WHICH checkout and
+* WHICH branch a run is executing in, so Phase 0 records an honest base-vs-
+* worktree branch split and lint fails when the recorded context no longer
+* matches live git state.
+*
+* Detection primitives:
+* - `isLinkedWorktree` — a directory is a linked git worktree when its private
+*   git dir (`git rev-parse --git-dir`) differs from the common git dir
+*   (`git rev-parse --git-common-dir`). The main checkout has both equal.
+* - `upstreamBranch` — the current branch's upstream target with the remote
+*   prefix stripped (origin/main -> main). Used to infer the promotion source
+*   branch for dev/stage/main workflows.
+*
+* Every accessor is total: on missing git or non-git dirs it returns null /
+* false, never throws. Callers defer rather than fail hard.
+*/
+/** Run git in a repo dir; return trimmed stdout or null on any failure. */
+function gitRun(repoRoot, ...args) {
+	try {
+		return execFileSync("git", args, {
+			cwd: repoRoot,
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim();
+	} catch {
+		return null;
+	}
+}
+/** True when a non-equal git-dir vs git-common-dir marks a linked worktree. */
+function isLinkedWorktree(gitDir, commonDir) {
+	if (!gitDir || !commonDir) return false;
+	return gitDir !== commonDir;
+}
+/** Strip a remote ref prefix (origin/main -> main, remotes/origin/main -> main). */
+function stripRemotePrefix(ref) {
+	if (!ref) return null;
+	const short = ref.trim().replace(/^refs\/remotes\//, "").replace(/^[^/]+\//, "");
+	return short === "" ? null : short;
+}
+/**
+* Gather normalized git facts about `repoRoot`. Total: any git failure
+* degrades to neutral values (false / null), never throws.
+*/
+function gitFacts(repoRoot) {
+	const gitDir = gitRun(repoRoot, "rev-parse", "--git-dir");
+	const commonDir = gitRun(repoRoot, "rev-parse", "--git-common-dir");
+	const headSha = gitRun(repoRoot, "rev-parse", "--verify", "HEAD^{commit}");
+	const branch = gitRun(repoRoot, "symbolic-ref", "--quiet", "--short", "HEAD");
+	const toplevel = gitRun(repoRoot, "rev-parse", "--show-toplevel");
+	const upstreamRef = gitRun(repoRoot, "rev-parse", "--abbrev-ref", "@{upstream}");
+	return {
+		headSha,
+		branch: branch || null,
+		detached: !branch,
+		isWorktree: isLinkedWorktree(gitDir, commonDir),
+		gitDir,
+		commonDir,
+		toplevel,
+		upstreamBranch: branch ? stripRemotePrefix(upstreamRef) : null
+	};
+}
+/**
+* Resolve the effective base branch for a checkout. In a linked worktree this
+* is the branch the work is based on — best inferred from the upstream target
+* (dev/stage/main promotion source) when one is configured; otherwise fall
+* back to the current branch. Returns null only when no branch exists.
+*/
+function resolveBaseBranch(facts) {
+	if (facts.branch && facts.upstreamBranch && facts.upstreamBranch !== facts.branch) return facts.upstreamBranch;
+	return facts.branch;
+}
+/**
+* Verify a worktree branch is (still) based on the recorded base branch.
+* Returns { ok, reason }. Fails when the base branch no longer exists, or the
+* worktree branch no longer contains it (merge-base --is-ancestor fails).
+* A missing/unresolvable branch degrades to ok:false with a reason; a
+* non-git dir degrades to ok:true (defer — nothing to verify).
+*/
+function verifyBranchBase(repoRoot, baseBranch, worktreeBranch) {
+	if (!baseBranch || !worktreeBranch) return {
+		ok: true,
+		reason: null
+	};
+	if (!gitRun(repoRoot, "rev-parse", "--git-dir")) return {
+		ok: true,
+		reason: null
+	};
+	if (!gitRun(repoRoot, "rev-parse", "--verify", `${baseBranch}^{commit}`)) return {
+		ok: false,
+		reason: `recorded base branch '${baseBranch}' does not resolve in this checkout`
+	};
+	if (!gitRun(repoRoot, "rev-parse", "--verify", `${worktreeBranch}^{commit}`)) return {
+		ok: false,
+		reason: `recorded worktree branch '${worktreeBranch}' does not resolve in this checkout`
+	};
+	try {
+		execFileSync("git", [
+			"-C",
+			repoRoot,
+			"merge-base",
+			"--is-ancestor",
+			baseBranch,
+			worktreeBranch
+		], { stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		] });
+		return {
+			ok: true,
+			reason: null
+		};
+	} catch {
+		return {
+			ok: false,
+			reason: `worktree branch '${worktreeBranch}' is not based on recorded base branch '${baseBranch}'`
+		};
+	}
+}
+/** Verify the recorded worktree branch matches the live HEAD branch. */
+function verifyWorktreeBranch(repoRoot, recordedBranch) {
+	if (!recordedBranch) return {
+		ok: true,
+		reason: null
+	};
+	const live = gitRun(repoRoot, "symbolic-ref", "--quiet", "--short", "HEAD");
+	if (!live) return {
+		ok: false,
+		reason: "HEAD is detached; expected branch " + recordedBranch
+	};
+	if (live !== recordedBranch) return {
+		ok: false,
+		reason: `checkout is on branch '${live}' but 00-worktree.md records '${recordedBranch}'`
+	};
+	return {
+		ok: true,
+		reason: null
+	};
+}
+//#endregion
 //#region src/phase-rules.ts
 /**
 * Phase rules (R5): canonical parity port of lint-recursive-run.py's
@@ -1048,6 +1196,24 @@ function getRunDiffBasis(runDir) {
 		notes: getMdFieldValue$1(source, "Diff basis notes") ?? getMdFieldValue$1(source, "Notes")
 	};
 }
+/**
+* verify_recorded_branches: worktree + branch awareness at lint time. Compares
+* the branches recorded in 00-worktree.md against live git state. Returns a
+* list of FAIL messages (empty when consistent). Both the base branch and the
+* worktree branch must resolve; the worktree branch must match the live HEAD
+* branch, and it must actually be based on the recorded base branch.
+*/
+function verifyRecordedBranches(repoRoot, diffBasis, runDir) {
+	const fails = [];
+	const baseBranch = trimMdValue$1(diffBasis.base_branch ?? "");
+	const worktreeBranch = trimMdValue$1(diffBasis.worktree_branch ?? "");
+	if (!baseBranch && !worktreeBranch) return fails;
+	const wtCheck = verifyWorktreeBranch(repoRoot, worktreeBranch || null);
+	if (!wtCheck.ok && wtCheck.reason) fails.push(wtCheck.reason);
+	const baseCheck = verifyBranchBase(repoRoot, baseBranch || null, worktreeBranch || null);
+	if (!baseCheck.ok && baseCheck.reason) fails.push(baseCheck.reason);
+	return fails;
+}
 /** normalize_diff_basis: validate + compute the executable diff basis. */
 function normalizeDiffBasis(repoRoot, diffBasis) {
 	const baselineType = normalizeBaselineType(diffBasis.baseline_type);
@@ -2612,6 +2778,11 @@ function lintRun(repoRoot, runId) {
 		let diffBasisError = null;
 		if (STRICT_WORKFLOW_PROFILES$1.has(workflowProfile)) {
 			const diffBasis = getRunDiffBasis(runDir);
+			const branchFails = verifyRecordedBranches(root, diffBasis, runDir);
+			for (const message of branchFails) {
+				totalFail += 1;
+				writeIssue("FAIL", runDir, message);
+			}
 			if (diffBasis.baseline_reference || diffBasis.normalized_baseline) {
 				const [rawChanged, gitError] = getGitChangedFiles(root, diffBasis);
 				if (gitError) {
@@ -2751,12 +2922,9 @@ function detectGitContext(repoRoot) {
 		context: {},
 		error: "Unable to resolve HEAD commit for Phase 0 diff basis prefill: git rev-parse returned no output"
 	};
-	const branch = run([
-		"symbolic-ref",
-		"--quiet",
-		"--short",
-		"HEAD"
-	]) || "(detached HEAD)";
+	const facts = gitFacts(repoRoot);
+	const branch = facts.branch ?? "(detached HEAD)";
+	const baseBranch = resolveBaseBranch(facts) ?? branch;
 	return {
 		context: {
 			baselineType: "local commit",
@@ -2765,9 +2933,11 @@ function detectGitContext(repoRoot) {
 			normalizedBaseline: headSha,
 			normalizedComparison: "working-tree",
 			normalizedDiffCommand: "git diff --name-only " + headSha,
-			baseBranch: branch,
+			baseBranch,
 			worktreeBranch: branch,
 			baseCommit: headSha,
+			isWorktree: facts.isWorktree,
+			upstreamBranch: facts.upstreamBranch,
 			notes: "recursive-init prefilled this executable diff basis from the current HEAD commit. If Phase 0 later changes the chosen baseline, update every diff-basis field and rerun lint before locking."
 		},
 		error: null
@@ -4687,6 +4857,272 @@ function renderRecursivePolicy(context) {
 	return lines.join("\n");
 }
 //#endregion
+//#region src/worktree.ts
+/**
+* worktree.ts — drive linked-worktree creation and branch promotion.
+*
+* Worktree + branch awareness, operational half (R?): after detection
+* (git-context.ts) and lint validation (ts-lint.ts), this module performs the
+* git operations that actually realize the dev/stage/main worktree workflow:
+*
+* - `createLinkedWorktree`: create a linked worktree at
+*   `<repoRoot>/.worktrees/<runId>/` on a worktree branch based on a base
+*   branch (default: the upstream/promotion source branch).
+* - `promoteBranch`: fast-forward one branch into a target promotion stage
+*   (feature -> dev -> stage -> main). The promotion is verified to be a
+*   fast-forward first (the target must be an ancestor of the source) and
+*   then applied where it is safe:
+*     - if the target branch is checked out in a worktree, `git merge
+*       --ff-only` runs THERE (safe: moves the branch and its working tree
+*       forward together, never a merge commit);
+*     - otherwise the branch ref is updated directly.
+*   It never rewrites history and never creates a merge commit.
+*
+* Both operations are explicit, workspace-scoped, and total: they return
+* { ok, ... } rather than corrupting git state. No operation ever touches a
+* branch other than the explicitly requested one.
+*/
+/** Run git; throw on failure (callers catch to turn into a result). */
+function gitThrow(repoRoot, ...args) {
+	return execFileSync("git", args, {
+		cwd: repoRoot,
+		encoding: "utf8",
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		]
+	}).trim();
+}
+/** Resolve the current branch of a repo dir (short name or null when detached). */
+function currentBranch(repoRoot) {
+	try {
+		return gitThrow(repoRoot, "symbolic-ref", "--quiet", "--short", "HEAD");
+	} catch {
+		return null;
+	}
+}
+/** Default worktree branch name for a run. */
+function defaultWorktreeBranch(runId) {
+	return "recursive/" + runId;
+}
+/** List linked worktrees (path + branch) for a repo root. */
+function listWorktrees(repoRoot) {
+	let out;
+	try {
+		out = gitThrow(repoRoot, "worktree", "list", "--porcelain");
+	} catch {
+		return [];
+	}
+	const result = [];
+	let current = null;
+	for (const line of out.split(/\r?\n/)) {
+		const trimmed = line.trim();
+		if (!trimmed) {
+			if (current) {
+				result.push(current);
+				current = null;
+			}
+			continue;
+		}
+		if (trimmed.startsWith("worktree ")) current = {
+			path: trimmed.slice(9),
+			branch: null,
+			detached: false
+		};
+		else if (trimmed.startsWith("branch refs/heads/") && current) current.branch = trimmed.slice(18);
+		else if (trimmed === "detached" && current) current.detached = true;
+	}
+	if (current) result.push(current);
+	return result;
+}
+/**
+* Find the worktree path where `branch` is currently checked out, or null.
+* Parses `git worktree list --porcelain` (block per worktree with a
+* `branch refs/heads/<name>` line).
+*/
+function findWorktreeForBranch(repoRoot, branch) {
+	let out;
+	try {
+		out = gitThrow(repoRoot, "worktree", "list", "--porcelain");
+	} catch {
+		return null;
+	}
+	let currentPath = null;
+	for (const line of out.split(/\r?\n/)) {
+		const trimmed = line.trim();
+		if (!trimmed) {
+			currentPath = null;
+			continue;
+		}
+		if (trimmed.startsWith("worktree ")) currentPath = trimmed.slice(9);
+		else if (trimmed.startsWith("branch refs/heads/")) {
+			if (trimmed.slice(18) === branch && currentPath) return currentPath;
+		}
+	}
+	return null;
+}
+/**
+* Create a linked worktree at `.worktrees/<runId>/` for a run. The worktree
+* branch is cut from `baseBranch` (default: the current HEAD branch). Returns
+* the created worktree dir + branch. No-op-safe: if the worktree dir already
+* exists, returns ok with the existing dir. Refuses to create a worktree when
+* the run directory already exists (prevents clobbering an in-progress run).
+*/
+function createLinkedWorktree(opts) {
+	const { repoRoot, runId } = opts;
+	const baseBranch = opts.baseBranch ?? currentBranch(repoRoot) ?? "main";
+	const worktreeBranch = opts.worktreeBranch ?? defaultWorktreeBranch(runId);
+	const worktreeDir = join(repoRoot, ".worktrees", runId);
+	if (existsSync(worktreeDir)) return {
+		ok: true,
+		worktreeDir,
+		worktreeBranch,
+		baseBranch,
+		error: void 0
+	};
+	const runDir = join(repoRoot, ".recursive", "run", runId);
+	if (existsSync(runDir)) return {
+		ok: false,
+		worktreeDir,
+		worktreeBranch,
+		baseBranch,
+		error: "run directory already exists: " + runDir + " (refusing to create a worktree for an existing run)"
+	};
+	try {
+		gitThrow(repoRoot, "rev-parse", "--verify", baseBranch + "^{commit}");
+	} catch {
+		return {
+			ok: false,
+			worktreeDir,
+			worktreeBranch,
+			baseBranch,
+			error: "base branch does not resolve: " + baseBranch
+		};
+	}
+	try {
+		gitThrow(repoRoot, "worktree", "add", "-b", worktreeBranch, worktreeDir, baseBranch);
+	} catch (err) {
+		return {
+			ok: false,
+			worktreeDir,
+			worktreeBranch,
+			baseBranch,
+			error: "git worktree add failed: " + err.message
+		};
+	}
+	return {
+		ok: true,
+		worktreeDir,
+		worktreeBranch,
+		baseBranch
+	};
+}
+/**
+* Fast-forward `toBranch` to `fromBranch` (promotion up the dev/stage/main
+* chain). Returns ok:false when the promotion is not a pure fast-forward
+* (would require a merge commit) or when the from/to branches are missing.
+*/
+function promoteBranch(opts) {
+	const { repoRoot, fromBranch, toBranch } = opts;
+	if (fromBranch === toBranch) return {
+		ok: false,
+		fromBranch,
+		toBranch,
+		action: "fast-forward",
+		error: "from and to branches are identical: " + fromBranch
+	};
+	let fromSha = null;
+	try {
+		fromSha = gitThrow(repoRoot, "rev-parse", "--verify", fromBranch + "^{commit}");
+	} catch {}
+	if (!fromSha) return {
+		ok: false,
+		fromBranch,
+		toBranch,
+		action: "fast-forward",
+		error: "from branch does not resolve: " + fromBranch
+	};
+	let toSha = null;
+	try {
+		toSha = gitThrow(repoRoot, "rev-parse", "--verify", toBranch + "^{commit}");
+	} catch {}
+	if (!toSha) try {
+		gitThrow(repoRoot, "branch", toBranch, fromSha);
+		return {
+			ok: true,
+			fromBranch,
+			toBranch,
+			action: "created"
+		};
+	} catch (err) {
+		return {
+			ok: false,
+			fromBranch,
+			toBranch,
+			action: "created",
+			error: "git branch failed: " + err.message
+		};
+	}
+	try {
+		execFileSync("git", [
+			"-C",
+			repoRoot,
+			"merge-base",
+			"--is-ancestor",
+			toBranch,
+			fromBranch
+		], { stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		] });
+	} catch {
+		return {
+			ok: false,
+			fromBranch,
+			toBranch,
+			action: "fast-forward",
+			error: "promotion is not a fast-forward: " + toBranch + " is not an ancestor of " + fromBranch
+		};
+	}
+	const checkedOutIn = findWorktreeForBranch(repoRoot, toBranch);
+	if (checkedOutIn) try {
+		gitThrow(checkedOutIn, "merge", "--ff-only", fromBranch);
+		return {
+			ok: true,
+			fromBranch,
+			toBranch,
+			action: "fast-forward"
+		};
+	} catch (err) {
+		return {
+			ok: false,
+			fromBranch,
+			toBranch,
+			action: "fast-forward",
+			error: "fast-forward merge in " + checkedOutIn + " failed: " + err.message
+		};
+	}
+	try {
+		gitThrow(repoRoot, "update-ref", "refs/heads/" + toBranch, fromSha);
+		return {
+			ok: true,
+			fromBranch,
+			toBranch,
+			action: "fast-forward"
+		};
+	} catch (err) {
+		return {
+			ok: false,
+			fromBranch,
+			toBranch,
+			action: "fast-forward",
+			error: "git update-ref failed: " + err.message
+		};
+	}
+}
+//#endregion
 //#region src/runtime.ts
 var RecursiveRuntime = class extends Service {
 	/** Recursive-mode runtime service. Owns run-state reads + lock/init/lint operations. */
@@ -4953,11 +5389,28 @@ var RecursiveRuntime = class extends Service {
 	* required section (get_artifact_required_sections) + TODO + FAIL gates.
 	* Also scaffolds addenda/subagents/router-prompts/evidence dirs. Returns the
 	* run dir + created artifacts.
+	*
+	* When `opts.createWorktree` is true, a linked worktree is first created at
+	* `.worktrees/<runId>/` and the run is scaffolded INSIDE it (per the
+	* "all subsequent phases execute in worktree context" rule). The worktree
+	* branch defaults to `recursive/<runId>` and is cut from `opts.baseBranch`
+	* (default: current HEAD branch of the root checkout).
 	*/
-	async initRun(runId, agent) {
+	async initRun(runId, agent, opts) {
 		const root = await this.resolveRootFor(agent);
 		if (!root) throw new Error("cannot resolve workspace control-plane root for this session");
-		const runDir = join(root, ".recursive", "run", runId);
+		let scaffoldRoot = root;
+		let worktree;
+		if (opts?.createWorktree) {
+			worktree = createLinkedWorktree({
+				repoRoot: root,
+				runId,
+				baseBranch: opts.baseBranch
+			});
+			if (!worktree.ok) throw new Error(worktree.error ?? "worktree create failed");
+			scaffoldRoot = worktree.worktreeDir;
+		}
+		const runDir = join(scaffoldRoot, ".recursive", "run", runId);
 		mkdirSync(runDir, { recursive: true });
 		const created = [];
 		const existing = [];
@@ -4970,8 +5423,8 @@ var RecursiveRuntime = class extends Service {
 			mkdirSync(p, { recursive: true });
 			created.push(dir + "/");
 		}
-		const { context: gitContext, error: prefillError } = detectGitContext(root);
-		const phase0 = [["00-requirements.md", requirementsContent(runId, "feature", "")], ["00-worktree.md", worktreeContent(runId, root, gitContext, prefillError)]];
+		const { context: gitContext, error: prefillError } = detectGitContext(scaffoldRoot);
+		const phase0 = [["00-requirements.md", requirementsContent(runId, "feature", "")], ["00-worktree.md", worktreeContent(runId, scaffoldRoot, gitContext, prefillError)]];
 		for (const [file, content] of phase0) {
 			const path = join(runDir, file);
 			if (existsSync(path)) {
@@ -5001,12 +5454,52 @@ var RecursiveRuntime = class extends Service {
 			writeFileSync(path, laterPhaseContent(runId, file), "utf8");
 			created.push(file);
 		}
-		return {
+		const result = {
 			runDir,
 			runId,
 			created,
 			existing
 		};
+		if (worktree) result.worktree = worktree;
+		return result;
+	}
+	/**
+	* Create a linked worktree for a run under the given workspace root. The
+	* worktree branch defaults to `recursive/<runId>` and is cut from the given
+	* base branch (default: the current HEAD branch of the root checkout).
+	* Refuses to create over an existing run directory. Workspace-scoped.
+	*/
+	createRunWorktree(root, runId, baseBranch) {
+		return createLinkedWorktree({
+			repoRoot: root,
+			runId,
+			baseBranch
+		});
+	}
+	/**
+	* Promote a branch up the dev/stage/main chain (fast-forward). Workspace-scoped.
+	*/
+	promoteRunBranch(root, fromBranch, toBranch) {
+		return promoteBranch({
+			repoRoot: root,
+			fromBranch,
+			toBranch
+		});
+	}
+	/**
+	* Worktree + branch status for a workspace root: the linked worktrees,
+	* which branch each is on, and the current checkout's base/upstream context.
+	*/
+	worktreeStatus(root) {
+		const facts = gitFacts(root);
+		const worktrees = listWorktrees(root);
+		return {
+			root,
+			isWorktree: facts.isWorktree,
+			branch: facts.branch,
+			upstreamBranch: facts.upstreamBranch,
+			worktrees
+		};
 	}
 	/**
 	* Lock a DRAFT artifact (or reopen a LOCKED one). Validates prerequisites;
@@ -5232,11 +5725,21 @@ function createRecursiveStatusTool(recursive) {
 function createRecursiveInitTool(recursive) {
 	return defineTool({
 		name: "recursive_init",
-		description: "Scaffold a new recursive-mode run directory (or ensure an existing one) with stub artifact headers. Delegates to the RecursiveRuntime service (no duplicated scaffolding logic).",
-		parameters: { runId: {
-			type: "string",
-			description: "Run id (e.g. 03-something). Required."
-		} },
+		description: "Scaffold a new recursive-mode run directory (or ensure an existing one) with stub artifact headers. Delegates to the RecursiveRuntime service (no duplicated scaffolding logic). When createWorktree is true, a linked worktree is created first and the run is scaffolded inside it.",
+		parameters: {
+			runId: {
+				type: "string",
+				description: "Run id (e.g. 03-something). Required."
+			},
+			createWorktree: {
+				type: "boolean",
+				description: "If true, create a linked worktree at .worktrees/<runId>/ and scaffold the run inside it (default: false)."
+			},
+			baseBranch: {
+				type: "string",
+				description: "Base branch the worktree branch is cut from (default: current HEAD branch). Only used when createWorktree is true."
+			}
+		},
 		output: {
 			schema: { type: "json" },
 			render: (_args, value) => [{
@@ -5247,7 +5750,10 @@ function createRecursiveInitTool(recursive) {
 		async execute(args, exec) {
 			if (!args.runId || args.runId.trim() === "") return { error: "runId is required" };
 			try {
-				return await recursive.initRun(args.runId.trim(), exec.agent);
+				return await recursive.initRun(args.runId.trim(), exec.agent, {
+					createWorktree: args.createWorktree === true,
+					baseBranch: args.baseBranch?.trim() || void 0
+				});
 			} catch (err) {
 				return { error: err instanceof Error ? err.message : String(err) };
 			}
@@ -5411,6 +5917,63 @@ function createRecursiveScratchTool(recursive) {
 	});
 }
 //#endregion
+//#region src/recursive_worktree.tool.ts
+/**
+* `recursive_worktree` — create a linked git worktree for a run and/or
+* promote a branch up the dev/stage/main chain. Workspace-scoped: the
+* operations run under the SESSION's control-plane root only.
+*/
+function createRecursiveWorktreeTool(recursive) {
+	return defineTool({
+		name: "recursive_worktree",
+		description: "Create a linked git worktree for a recursive-mode run and/or promote a branch up the dev/stage/main chain. Workspace-scoped under the current session workspace.",
+		parameters: {
+			runId: {
+				type: "string",
+				description: "Run id the worktree is created for (e.g. 03-something). Required for create."
+			},
+			action: {
+				type: "string",
+				description: "create | promote | status. Default: create."
+			},
+			fromBranch: {
+				type: "string",
+				description: "Source branch for a promote action (the branch holding the new commits)."
+			},
+			toBranch: {
+				type: "string",
+				description: "Promotion target branch for a promote action (feature -> dev -> stage -> main)."
+			},
+			baseBranch: {
+				type: "string",
+				description: "Base branch the worktree branch is cut from (default: current HEAD branch)."
+			}
+		},
+		output: {
+			schema: { type: "json" },
+			render: (_args, value) => [{
+				type: "text",
+				text: JSON.stringify(value, null, 2)
+			}]
+		},
+		async execute(args, exec) {
+			const action = args.action ?? "create";
+			const root = await recursive.resolveRootFor(exec.agent);
+			if (!root) return { error: "session is not attached to a registered workspace (cannot resolve control-plane root)" };
+			if (action === "create") {
+				if (!args.runId || args.runId.trim() === "") return { error: "runId is required for create" };
+				return recursive.createRunWorktree(root, args.runId.trim(), args.baseBranch?.trim() || void 0);
+			}
+			if (action === "promote") {
+				if (!args.fromBranch || !args.toBranch) return { error: "fromBranch and toBranch are required for promote" };
+				return recursive.promoteRunBranch(root, args.fromBranch.trim(), args.toBranch.trim());
+			}
+			if (action === "status") return recursive.worktreeStatus(root);
+			return { error: "action must be create | promote | status" };
+		}
+	});
+}
+//#endregion
 //#region src/bootstrap.ts
 /**
 * Idempotent scaffold installer (R3). TS port of install-recursive-mode.py's
@@ -5851,6 +6414,46 @@ function executeRecursiveCommand(root, rawInput) {
 				text: "closeout scaffolded for " + runId + " phase " + phase
 			};
 		}
+		case "worktree": {
+			const parts = arg.trim().split(/\s+/);
+			const op = parts[0] ?? "";
+			if (op === "status") return {
+				kind: "success",
+				text: "worktree status for workspace " + root
+			};
+			if (op === "create") {
+				const runId = parts[1] ?? "";
+				if (!runId) return {
+					kind: "error",
+					text: "worktree create requires a run id"
+				};
+				const runDir = join(runRoot, runId);
+				if (existsSync(runDir)) return {
+					kind: "error",
+					text: "Run already exists in this workspace: " + runId
+				};
+				return {
+					kind: "success",
+					text: "worktree created for run " + runId + " at .worktrees/" + runId
+				};
+			}
+			if (op === "promote") {
+				const fromBranch = parts[1] ?? "";
+				const toBranch = parts[2] ?? "";
+				if (!fromBranch || !toBranch) return {
+					kind: "error",
+					text: "worktree promote requires <from> <to>"
+				};
+				return {
+					kind: "success",
+					text: "promoted " + fromBranch + " -> " + toBranch
+				};
+			}
+			return {
+				kind: "error",
+				text: "worktree requires create|promote|status"
+			};
+		}
 		case "scratch": {
 			const runId = arg.trim();
 			if (!runId) return {
@@ -5916,6 +6519,48 @@ function registerRecursiveCommand(ctx, recursive) {
 					};
 				}
 			}
+			if (verb === "worktree" && arg) {
+				const parts = arg.trim().split(/\s+/);
+				const op = parts[0] ?? "";
+				if (op === "create") {
+					const runId = parts[1] ?? "";
+					const baseBranch = arg.match(/--base\s+(\S+)/)?.[1];
+					if (!runId) return {
+						kind: "error",
+						text: "worktree create requires a run id"
+					};
+					const result = recursive.createRunWorktree(root, runId, baseBranch);
+					if (!result.ok) return {
+						kind: "error",
+						text: result.error ?? "worktree create failed"
+					};
+					return {
+						kind: "success",
+						text: "worktree created: " + JSON.stringify(result)
+					};
+				}
+				if (op === "promote") {
+					const fromBranch = parts[1] ?? "";
+					const toBranch = parts[2] ?? "";
+					if (!fromBranch || !toBranch) return {
+						kind: "error",
+						text: "worktree promote requires <from> <to>"
+					};
+					const result = recursive.promoteRunBranch(root, fromBranch, toBranch);
+					if (!result.ok) return {
+						kind: "error",
+						text: result.error ?? "promote failed"
+					};
+					return {
+						kind: "success",
+						text: "promoted: " + JSON.stringify(result)
+					};
+				}
+				if (op === "status") return {
+					kind: "success",
+					text: "worktree status: " + JSON.stringify(recursive.worktreeStatus(root))
+				};
+			}
 			return executeRecursiveCommand(root, rawInput);
 		}
 	});
@@ -6206,7 +6851,8 @@ function apply(ctx, config) {
 			ctx.tools.register(createRecursiveLockTool(recursive)),
 			ctx.tools.register(createRecursiveLintTool(recursive)),
 			ctx.tools.register(createRecursiveCloseoutTool(recursive)),
-			ctx.tools.register(createRecursiveScratchTool(recursive))
+			ctx.tools.register(createRecursiveScratchTool(recursive)),
+			ctx.tools.register(createRecursiveWorktreeTool(recursive))
 		];
 		const commands = ctx.get("commands");
 		if (commands) disposers.push(registerRecursiveCommand({ commands }, recursive));
@@ -6308,4 +6954,4 @@ function apply(ctx, config) {
 	});
 }
 //#endregion
-export { DEFAULT_ENFORCEMENT, LifecycleDriver, OPTIONAL_PHASES, PHASES, PHASE_SEQUENCE, RECURSIVE_API_PREFIX, RUN_ARTIFACT_SEQUENCE, RUN_STATES, RecursiveRuntime, apply, buildDelegationPrompt, buildReviewBundle, capabilityProbe, childScratchPath, contentSha256, coupleGateBlockToGoal, createChildBrief, createHandoff, createRecursiveCloseoutTool, createRecursiveInitTool, createRecursiveLintTool, createRecursiveLockTool, createRecursiveScratchTool, createRecursiveStatusTool, defaultReviewToolFilter, delegate, delegationDecisionBasis, delegationError, detectTamper, detectTransitionIntent, discoverRuns, escapeRegExp, evaluateDelegationResult, evaluatePreStepGate, evaluateToolGuard, foldRecursivePhase, foldRun, foldRunCard, getAllStaleReceipts, getArtifactState, getGateStatus, getLatestRunDirectory, getLockStatus, getMdFieldValue, getNextLegalPhase, getPrerequisiteBlockers, getPrerequisites, getStaleDownstreamPhases, getTodoStats, getWorkflowProfile, hasOpenTurn, inject, invalidateReceipt, isCoreArtifact, loadRouterPolicy, lockHashFromContent, makeRecursiveRoutes, mountRecursiveRoutesOnce, name, normalizeForLockHash, phaseIndex, probeCapabilities, readReceipt, receiptPath, renderRecursivePolicy, replyPath, resolveEnforcementConfig, resolveRole, resolveRunDir, reviewBundleDir, reviewOutputSchema, routerPolicyPath, snapshotWorkspace, trimMdValue, validateChain, validateReferences, validateTransition, writeActionRecord, writeReceipt };
+export { DEFAULT_ENFORCEMENT, LifecycleDriver, OPTIONAL_PHASES, PHASES, PHASE_SEQUENCE, RECURSIVE_API_PREFIX, RUN_ARTIFACT_SEQUENCE, RUN_STATES, RecursiveRuntime, apply, buildDelegationPrompt, buildReviewBundle, capabilityProbe, childScratchPath, contentSha256, coupleGateBlockToGoal, createChildBrief, createHandoff, createRecursiveCloseoutTool, createRecursiveInitTool, createRecursiveLintTool, createRecursiveLockTool, createRecursiveScratchTool, createRecursiveStatusTool, createRecursiveWorktreeTool, defaultReviewToolFilter, delegate, delegationDecisionBasis, delegationError, detectTamper, detectTransitionIntent, discoverRuns, escapeRegExp, evaluateDelegationResult, evaluatePreStepGate, evaluateToolGuard, foldRecursivePhase, foldRun, foldRunCard, getAllStaleReceipts, getArtifactState, getGateStatus, getLatestRunDirectory, getLockStatus, getMdFieldValue, getNextLegalPhase, getPrerequisiteBlockers, getPrerequisites, getStaleDownstreamPhases, getTodoStats, getWorkflowProfile, hasOpenTurn, inject, invalidateReceipt, isCoreArtifact, loadRouterPolicy, lockHashFromContent, makeRecursiveRoutes, mountRecursiveRoutesOnce, name, normalizeForLockHash, phaseIndex, probeCapabilities, readReceipt, receiptPath, renderRecursivePolicy, replyPath, resolveEnforcementConfig, resolveRole, resolveRunDir, reviewBundleDir, reviewOutputSchema, routerPolicyPath, snapshotWorkspace, trimMdValue, validateChain, validateReferences, validateTransition, writeActionRecord, writeReceipt };