@jawcode-dev/coding-agent 1.1.0

package/src/jwc-runtime/launch-tmux.ts

@@ -0,0 +1,296 @@
+import * as path from "node:path";
+import type { Args } from "../cli/args";
+import {
+	buildJwcTmuxProfileCommands,
+	buildJwcTmuxSessionName,
+	buildJwcTmuxSessionSlug,
+	GJC_DEFAULT_TMUX_SESSION,
+	GJC_TMUX_COMMAND_ENV,
+	GJC_TMUX_MOUSE_ENV,
+	GJC_TMUX_PROFILE_ENV,
+	GJC_TMUX_SESSION_PREFIX,
+	type JwcTmuxProfileCommand,
+	resolveJwcTmuxCommand,
+} from "./tmux-common";
+import { findJwcTmuxSessionByBranch } from "./tmux-sessions";
+
+export {
+	buildJwcTmuxProfileCommands,
+	GJC_DEFAULT_TMUX_SESSION,
+	GJC_TMUX_COMMAND_ENV,
+	GJC_TMUX_MOUSE_ENV,
+	GJC_TMUX_PROFILE_ENV,
+	GJC_TMUX_SESSION_PREFIX,
+};
+
+export const GJC_TMUX_LAUNCHED_ENV = "GJC_TMUX_LAUNCHED";
+export const GJC_LAUNCH_POLICY_ENV = "GJC_LAUNCH_POLICY";
+
+type LaunchPolicy = "direct" | "tmux";
+
+interface TtyState {
+	stdin: boolean;
+	stdout: boolean;
+}
+
+export interface TmuxLaunchContext {
+	parsed: Args;
+	rawArgs: string[];
+	cwd?: string;
+	env?: NodeJS.ProcessEnv;
+	argv?: string[];
+	execPath?: string;
+	platform?: NodeJS.Platform;
+	tty?: TtyState;
+	spawnSync?: TmuxSpawnSync;
+	tmuxAvailable?: boolean;
+	worktreeBranch?: string | null;
+	currentBranch?: string | null;
+	existingBranchSessionName?: string | null;
+	project?: string | null;
+	diagnosticWriter?: (message: string) => void;
+}
+
+export interface TmuxSpawnResult {
+	exitCode: number | null;
+	signalCode?: string | null;
+	stderr?: string;
+}
+
+export type TmuxSpawnSync = (command: string, args: string[], options: TmuxSpawnOptions) => TmuxSpawnResult;
+
+export interface TmuxSpawnOptions {
+	cwd: string;
+	env: NodeJS.ProcessEnv;
+	stdin: "inherit";
+	stdout: "inherit";
+	stderr: "inherit";
+}
+
+export interface TmuxLaunchPlan {
+	tmuxCommand: string;
+	sessionName: string;
+	cwd: string;
+	innerCommand: string;
+	newSessionArgs: string[];
+	branch?: string | null;
+	attachSessionName?: string;
+	project?: string | null;
+}
+
+export interface JwcTmuxProfileResult {
+	skipped: boolean;
+	commands: JwcTmuxProfileCommand[];
+	failures: Array<{ command: JwcTmuxProfileCommand; stderr?: string }>;
+}
+
+export interface JwcTmuxProfileContext {
+	tmuxCommand: string;
+	target: string;
+	cwd?: string;
+	env?: NodeJS.ProcessEnv;
+	spawnSync?: TmuxSpawnSync;
+	branch?: string | null;
+	branchSlug?: string | null;
+	project?: string | null;
+}
+
+interface CommandResolutionContext {
+	cwd: string;
+	argv: string[];
+	execPath: string;
+}
+
+function parseLaunchPolicy(env: NodeJS.ProcessEnv): LaunchPolicy {
+	const raw = (env.JWC_LAUNCH_POLICY ?? env[GJC_LAUNCH_POLICY_ENV])?.trim().toLowerCase();
+	if (raw === "direct" || raw === "tmux") return raw;
+	if (env.GJC_NO_TMUX === "1" || env.GJC_NO_TMUX === "true") return "direct";
+	return "tmux";
+}
+
+function isInteractiveRootLaunch(parsed: Args, tty: TtyState): boolean {
+	return (
+		tty.stdin &&
+		tty.stdout &&
+		!parsed.help &&
+		!parsed.version &&
+		!parsed.print &&
+		parsed.mode === undefined &&
+		parsed.export === undefined &&
+		parsed.listModels === undefined
+	);
+}
+
+function isBunVirtualPath(value: string | undefined): boolean {
+	return value?.startsWith("/$bunfs/") === true;
+}
+
+function formatTmuxLaunchDiagnostic(stage: string, stderr?: string): string {
+	const detail = stderr?.trim();
+	const suffix = detail ? ` ${detail.slice(0, 240)}` : "";
+	return `jwc --tmux failed after creating tmux session: ${stage}.${suffix}\n`;
+}
+
+function shellQuote(value: string): string {
+	if (value.length === 0) return "''";
+	return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+export function applyJwcTmuxProfile(context: JwcTmuxProfileContext): JwcTmuxProfileResult {
+	const env = context.env ?? process.env;
+	const branchSlug = context.branch ? buildJwcTmuxSessionSlug(context.branch) : (context.branchSlug ?? null);
+	const commands = buildJwcTmuxProfileCommands(context.target, env, {
+		branch: context.branch ?? null,
+		branchSlug,
+		project: context.project ?? null,
+	});
+	if (commands.length === 0) return { skipped: true, commands: [], failures: [] };
+	const spawnSync = context.spawnSync ?? defaultSpawnSync;
+	const cwd = context.cwd ?? process.cwd();
+	const options: TmuxSpawnOptions = { cwd, env, stdin: "inherit", stdout: "inherit", stderr: "inherit" };
+	const failures: JwcTmuxProfileResult["failures"] = [];
+	for (const command of commands) {
+		const result = spawnSync(context.tmuxCommand, command.args, options);
+		if (result.exitCode !== 0) failures.push({ command, stderr: result.stderr });
+	}
+	return { skipped: false, commands, failures };
+}
+
+function resolveCurrentJwcCommand(context: CommandResolutionContext): string[] {
+	const entrypoint = context.argv[1];
+	if (!entrypoint) return ["jwc"];
+	if (isBunVirtualPath(entrypoint)) {
+		return isBunVirtualPath(context.execPath) ? ["jwc"] : [context.execPath];
+	}
+	const resolvedEntrypoint = path.isAbsolute(entrypoint) ? entrypoint : path.resolve(context.cwd, entrypoint);
+	if (entrypoint.endsWith(".ts") || entrypoint.endsWith(".js") || entrypoint.endsWith(".mjs")) {
+		return [context.execPath, resolvedEntrypoint];
+	}
+	return [resolvedEntrypoint];
+}
+
+function buildInnerCommand(context: CommandResolutionContext, rawArgs: string[]): string {
+	const command = resolveCurrentJwcCommand(context);
+	const quoted = [...command, ...rawArgs].map(shellQuote).join(" ");
+	return `exec env ${GJC_TMUX_LAUNCHED_ENV}=1 ${quoted}`;
+}
+
+function readCurrentBranch(cwd: string): string | null {
+	try {
+		const result = Bun.spawnSync(["git", "symbolic-ref", "--quiet", "--short", "HEAD"], {
+			cwd,
+			stdout: "pipe",
+			stderr: "ignore",
+		});
+		if (result.exitCode !== 0) return null;
+		const branch = result.stdout.toString().trim();
+		return branch || null;
+	} catch {
+		return null;
+	}
+}
+
+function cleanupCreatedTmuxSession(plan: TmuxLaunchPlan, spawnSync: TmuxSpawnSync, options: TmuxSpawnOptions): void {
+	spawnSync(plan.tmuxCommand, ["kill-session", "-t", `=${plan.sessionName}`], options);
+}
+
+export function buildDefaultTmuxLaunchPlan(context: TmuxLaunchContext): TmuxLaunchPlan | undefined {
+	const env = context.env ?? process.env;
+	const policy = parseLaunchPolicy(env);
+	if (!context.parsed.tmux || policy === "direct") return undefined;
+	if (env.TMUX || env[GJC_TMUX_LAUNCHED_ENV] === "1") return undefined;
+	const platform = context.platform ?? process.platform;
+	if (platform === "win32") return undefined;
+	const tty = context.tty ?? { stdin: Boolean(process.stdin.isTTY), stdout: Boolean(process.stdout.isTTY) };
+	if (policy === "tmux" && !isInteractiveRootLaunch(context.parsed, tty)) return undefined;
+
+	const cwd = context.cwd ?? process.cwd();
+	const branch = context.worktreeBranch ?? context.currentBranch ?? readCurrentBranch(cwd);
+	const project = context.project ?? cwd;
+	const sessionName = buildJwcTmuxSessionName(env, { branch });
+	const tmuxCommand = resolveJwcTmuxCommand(env);
+	const tmuxAvailable = context.tmuxAvailable ?? Bun.which(tmuxCommand) !== null;
+	if (!tmuxAvailable) return undefined;
+	const existingBranchSessionName =
+		"existingBranchSessionName" in context
+			? (context.existingBranchSessionName ?? undefined)
+			: context.worktreeBranch
+				? findJwcTmuxSessionByBranch(context.worktreeBranch, env, project)?.name
+				: undefined;
+	const innerCommand = buildInnerCommand(
+		{
+			cwd,
+			argv: context.argv ?? process.argv,
+			execPath: context.execPath ?? process.execPath,
+		},
+		context.rawArgs,
+	);
+	return {
+		tmuxCommand,
+		sessionName,
+		cwd,
+		innerCommand,
+		newSessionArgs: ["new-session", "-d", "-s", sessionName, "-c", cwd, innerCommand],
+		branch,
+		project,
+		attachSessionName: existingBranchSessionName,
+	};
+}
+
+function defaultSpawnSync(command: string, args: string[], options: TmuxSpawnOptions): TmuxSpawnResult {
+	const result = Bun.spawnSync({
+		cmd: [command, ...args],
+		cwd: options.cwd,
+		env: options.env,
+		stdin: options.stdin,
+		stdout: options.stdout,
+		stderr: options.stderr,
+	});
+	return { exitCode: result.exitCode, signalCode: result.signalCode };
+}
+
+export function launchDefaultTmuxIfNeeded(context: TmuxLaunchContext): boolean {
+	const plan = buildDefaultTmuxLaunchPlan(context);
+	if (!plan) return false;
+	const env = context.env ?? process.env;
+	const spawnSync = context.spawnSync ?? defaultSpawnSync;
+	const options: TmuxSpawnOptions = {
+		cwd: plan.cwd,
+		env,
+		stdin: "inherit",
+		stdout: "inherit",
+		stderr: "inherit",
+	};
+	if (plan.attachSessionName) {
+		const attached = spawnSync(plan.tmuxCommand, ["attach-session", "-t", `=${plan.attachSessionName}`], options);
+		return attached.exitCode === 0;
+	}
+	const created = spawnSync(plan.tmuxCommand, plan.newSessionArgs, options);
+	if (created.exitCode === 0) {
+		const profile = applyJwcTmuxProfile({
+			tmuxCommand: plan.tmuxCommand,
+			target: plan.sessionName,
+			cwd: plan.cwd,
+			env,
+			spawnSync,
+			branch: plan.branch,
+			project: plan.project,
+		});
+		if (profile.failures.length > 0) {
+			cleanupCreatedTmuxSession(plan, spawnSync, options);
+			const failure =
+				profile.failures.find(item => item.command.args.includes("@gjc-profile")) ?? profile.failures[0];
+			(context.diagnosticWriter ?? process.stderr.write.bind(process.stderr))(
+				formatTmuxLaunchDiagnostic("profile tagging failed", failure?.stderr),
+			);
+			return true;
+		}
+	}
+	if (created.exitCode !== 0) return false;
+	const attached = spawnSync(plan.tmuxCommand, ["attach-session", "-t", plan.sessionName], options);
+	if (attached.exitCode === 0) return true;
+	(context.diagnosticWriter ?? process.stderr.write.bind(process.stderr))(
+		formatTmuxLaunchDiagnostic("attach failed", attached.stderr),
+	);
+	return true;
+}

package/src/jwc-runtime/launch-worktree.ts

@@ -0,0 +1,291 @@
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export type JwcLaunchWorktreeMode =
+	| { enabled: false }
+	| { enabled: true; detached: true; name: null }
+	| { enabled: true; detached: false; name: string };
+
+export interface ParsedLaunchWorktreeMode {
+	mode: JwcLaunchWorktreeMode;
+	remainingArgs: string[];
+}
+
+export interface JwcLaunchWorktreePlan {
+	enabled: true;
+	repoRoot: string;
+	worktreePath: string;
+	detached: boolean;
+	baseRef: string;
+	branchName: string | null;
+}
+
+export interface JwcLaunchWorktreeResult extends JwcLaunchWorktreePlan {
+	created: boolean;
+	reused: boolean;
+	createdBranch: boolean;
+	dirty?: boolean;
+}
+
+interface GitWorktreeEntry {
+	path: string;
+	head: string;
+	branchRef: string | null;
+	detached: boolean;
+}
+
+const BRANCH_IN_USE_PATTERN = /already checked out|already used by worktree|is already checked out/i;
+
+function runGit(cwd: string, args: string[]): string {
+	const result = Bun.spawnSync(["git", ...args], { cwd, stdout: "pipe", stderr: "pipe" });
+	if (result.exitCode === 0) return result.stdout.toString().trim();
+	const stderr = result.stderr.toString().trim();
+	throw new Error(stderr || `git ${args.join(" ")} failed`);
+}
+
+function tryRunGit(cwd: string, args: string[]): string | null {
+	const result = Bun.spawnSync(["git", ...args], { cwd, stdout: "pipe", stderr: "pipe" });
+	return result.exitCode === 0 ? result.stdout.toString().trim() : null;
+}
+
+function sanitizePathToken(value: string): string {
+	const readable = value
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/-+/g, "-")
+		.replace(/^-|-$/g, "");
+	const prefix = readable || "default";
+	const digest = crypto.createHash("sha256").update(value).digest("hex").slice(0, 8);
+	return `${prefix}-${digest}`;
+}
+
+function resolveSourceBranchSlug(repoRoot: string, baseRef: string): string {
+	const branch = tryRunGit(repoRoot, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
+	if (branch) return sanitizePathToken(branch);
+	return `head-${baseRef.slice(0, 12)}`;
+}
+
+function branchExists(repoRoot: string, branchName: string): boolean {
+	const result = Bun.spawnSync(["git", "show-ref", "--verify", "--quiet", `refs/heads/${branchName}`], {
+		cwd: repoRoot,
+		stdout: "ignore",
+		stderr: "ignore",
+	});
+	return result.exitCode === 0;
+}
+
+function validateBranchName(repoRoot: string, branchName: string): void {
+	const result = Bun.spawnSync(["git", "check-ref-format", "--branch", branchName], {
+		cwd: repoRoot,
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	if (result.exitCode === 0) return;
+	const stderr = result.stderr.toString().trim();
+	throw new Error(stderr || `invalid_worktree_branch:${branchName}`);
+}
+
+function listWorktrees(repoRoot: string): GitWorktreeEntry[] {
+	const raw = runGit(repoRoot, ["worktree", "list", "--porcelain"]);
+	if (!raw) return [];
+	return raw
+		.split(/\n\n+/)
+		.map(chunk => chunk.trim())
+		.filter(Boolean)
+		.flatMap(chunk => {
+			const lines = chunk
+				.split(/\r?\n/)
+				.map(line => line.trim())
+				.filter(Boolean);
+			const worktreeLine = lines.find(line => line.startsWith("worktree "));
+			const headLine = lines.find(line => line.startsWith("HEAD "));
+			const branchLine = lines.find(line => line.startsWith("branch "));
+			if (!worktreeLine || !headLine) return [];
+			return [
+				{
+					path: path.resolve(worktreeLine.slice("worktree ".length)),
+					head: headLine.slice("HEAD ".length).trim(),
+					branchRef: branchLine ? branchLine.slice("branch ".length).trim() : null,
+					detached: lines.includes("detached") || !branchLine,
+				},
+			];
+		});
+}
+
+function findWorktreeByPath(entries: GitWorktreeEntry[], worktreePath: string): GitWorktreeEntry | null {
+	const resolved = path.resolve(worktreePath);
+	return entries.find(entry => path.resolve(entry.path) === resolved) ?? null;
+}
+
+function hasBranchInUse(entries: GitWorktreeEntry[], branchName: string, worktreePath: string): boolean {
+	const expectedRef = `refs/heads/${branchName}`;
+	const resolvedPath = path.resolve(worktreePath);
+	return entries.some(entry => entry.branchRef === expectedRef && path.resolve(entry.path) !== resolvedPath);
+}
+
+function pruneStaleWorktreePath(repoRoot: string): void {
+	runGit(repoRoot, ["worktree", "prune"]);
+}
+
+function readWorktreeEntryFromPath(repoRoot: string, worktreePath: string): GitWorktreeEntry | null {
+	if (!fs.existsSync(worktreePath)) return null;
+	const repoCommonDir = tryRunGit(repoRoot, ["rev-parse", "--git-common-dir"]);
+	const worktreeCommonDir = tryRunGit(worktreePath, ["rev-parse", "--git-common-dir"]);
+	if (!repoCommonDir || !worktreeCommonDir) return null;
+	if (path.resolve(repoRoot, repoCommonDir) !== path.resolve(worktreePath, worktreeCommonDir)) return null;
+	const head = tryRunGit(worktreePath, ["rev-parse", "HEAD"]);
+	if (!head) return null;
+	const branchRef = tryRunGit(worktreePath, ["symbolic-ref", "-q", "HEAD"]);
+	return { path: path.resolve(worktreePath), head, branchRef, detached: !branchRef };
+}
+
+function isWorktreeDirty(worktreePath: string): boolean {
+	return runGit(worktreePath, ["status", "--porcelain"]).length > 0;
+}
+
+function resolveOptionalWorktreeName(args: string[], index: number): { name: string | null; nextIndex: number } {
+	const next = args[index + 1];
+	if (!next) return { name: null, nextIndex: index };
+	if (next === "--") return { name: null, nextIndex: index + 1 };
+	if (next.startsWith("-")) return { name: null, nextIndex: index };
+	return { name: next.trim() || null, nextIndex: index + 1 };
+}
+
+export function parseLaunchWorktreeMode(args: string[]): ParsedLaunchWorktreeMode {
+	let mode: JwcLaunchWorktreeMode = { enabled: false };
+	const remainingArgs: string[] = [];
+
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index] ?? "";
+		if (arg === "--worktree" || arg === "-w") {
+			const parsed = resolveOptionalWorktreeName(args, index);
+			mode = parsed.name
+				? { enabled: true, detached: false, name: parsed.name }
+				: { enabled: true, detached: true, name: null };
+			index = parsed.nextIndex;
+			continue;
+		}
+		if (arg.startsWith("--worktree=")) {
+			const name = arg.slice("--worktree=".length).trim();
+			mode = name ? { enabled: true, detached: false, name } : { enabled: true, detached: true, name: null };
+			continue;
+		}
+		if (arg.startsWith("-w=") || (arg.startsWith("-w") && arg.length > 2)) {
+			const name = arg.startsWith("-w=") ? arg.slice("-w=".length).trim() : arg.slice(2).trim();
+			mode = name ? { enabled: true, detached: false, name } : { enabled: true, detached: true, name: null };
+			continue;
+		}
+		remainingArgs.push(arg);
+	}
+
+	return { mode, remainingArgs };
+}
+
+export function planLaunchWorktree(
+	cwd: string,
+	mode: JwcLaunchWorktreeMode,
+): JwcLaunchWorktreePlan | { enabled: false } {
+	if (!mode.enabled) return { enabled: false };
+	const repoRoot = runGit(cwd, ["rev-parse", "--show-toplevel"]);
+	const baseRef = runGit(repoRoot, ["rev-parse", "HEAD"]);
+	const branchName = mode.detached ? null : mode.name;
+	if (branchName) validateBranchName(repoRoot, branchName);
+	const bucket = `${path.basename(repoRoot)}.jawcode-worktrees`;
+	const worktreeSlug = mode.detached ? resolveSourceBranchSlug(repoRoot, baseRef) : sanitizePathToken(mode.name);
+	const worktreePath = path.join(path.dirname(repoRoot), bucket, worktreeSlug);
+	return { enabled: true, repoRoot, worktreePath, detached: mode.detached, baseRef, branchName };
+}
+
+export function ensureLaunchWorktree(
+	plan: JwcLaunchWorktreePlan | { enabled: false },
+): JwcLaunchWorktreeResult | { enabled: false } {
+	if (!plan.enabled) return { enabled: false };
+	let allWorktrees = listWorktrees(plan.repoRoot);
+	const staleAtPath = findWorktreeByPath(allWorktrees, plan.worktreePath);
+	if (staleAtPath && !fs.existsSync(staleAtPath.path)) {
+		pruneStaleWorktreePath(plan.repoRoot);
+		allWorktrees = listWorktrees(plan.repoRoot);
+	}
+
+	const existingAtPath =
+		findWorktreeByPath(allWorktrees, plan.worktreePath) ??
+		readWorktreeEntryFromPath(plan.repoRoot, plan.worktreePath);
+	const expectedBranchRef = plan.branchName ? `refs/heads/${plan.branchName}` : null;
+
+	if (existingAtPath) {
+		let dirty = isWorktreeDirty(plan.worktreePath);
+		if (plan.detached) {
+			if (!existingAtPath.detached) {
+				throw new Error(`worktree_target_mismatch:${plan.worktreePath}`);
+			}
+			if (existingAtPath.head !== plan.baseRef) {
+				if (dirty) throw new Error(`worktree_dirty:${plan.worktreePath}`);
+				runGit(plan.worktreePath, ["checkout", "--detach", plan.baseRef]);
+				dirty = false;
+			}
+		} else if (existingAtPath.branchRef !== expectedBranchRef) {
+			throw new Error(`worktree_target_mismatch:${plan.worktreePath}`);
+		}
+		return {
+			...plan,
+			worktreePath: path.resolve(plan.worktreePath),
+			created: false,
+			reused: true,
+			createdBranch: false,
+			...(dirty ? { dirty: true } : {}),
+		};
+	}
+
+	if (fs.existsSync(plan.worktreePath)) throw new Error(`worktree_path_conflict:${plan.worktreePath}`);
+	if (plan.branchName && hasBranchInUse(allWorktrees, plan.branchName, plan.worktreePath)) {
+		throw new Error(`branch_in_use:${plan.branchName}`);
+	}
+
+	fs.mkdirSync(path.dirname(plan.worktreePath), { recursive: true });
+	const branchAlreadyExisted = plan.branchName ? branchExists(plan.repoRoot, plan.branchName) : false;
+	const args = ["worktree", "add"];
+	if (plan.detached) args.push("--detach", plan.worktreePath, plan.baseRef);
+	else if (branchAlreadyExisted) args.push(plan.worktreePath, plan.branchName ?? "");
+	else args.push("-b", plan.branchName ?? "", plan.worktreePath, plan.baseRef);
+
+	const result = Bun.spawnSync(["git", ...args], { cwd: plan.repoRoot, stdout: "pipe", stderr: "pipe" });
+	if (result.exitCode !== 0) {
+		const stderr = result.stderr.toString().trim();
+		if (plan.branchName && BRANCH_IN_USE_PATTERN.test(stderr)) throw new Error(`branch_in_use:${plan.branchName}`);
+		throw new Error(stderr || `worktree_add_failed:${args.join(" ")}`);
+	}
+
+	return {
+		...plan,
+		worktreePath: path.resolve(plan.worktreePath),
+		created: true,
+		reused: false,
+		createdBranch: Boolean(plan.branchName && !branchAlreadyExisted),
+	};
+}
+
+export function ensureReusableNodeModules(sourceRoot: string, worktreePath: string): "symlink" | "present" | "missing" {
+	const target = path.join(worktreePath, "node_modules");
+	if (fs.existsSync(target)) return "present";
+	const source = path.join(sourceRoot, "node_modules");
+	if (!fs.existsSync(source)) return "missing";
+	fs.symlinkSync(source, target, "junction");
+	return "symlink";
+}
+
+export function prepareLaunchWorktree(
+	cwd: string,
+	args: string[],
+): {
+	cwd: string;
+	args: string[];
+	worktree: JwcLaunchWorktreeResult | { enabled: false };
+} {
+	const parsed = parseLaunchWorktreeMode(args);
+	const planned = planLaunchWorktree(cwd, parsed.mode);
+	const ensured = ensureLaunchWorktree(planned);
+	if (!ensured.enabled) return { cwd, args: parsed.remainingArgs, worktree: ensured };
+	ensureReusableNodeModules(ensured.repoRoot, ensured.worktreePath);
+	return { cwd: ensured.worktreePath, args: parsed.remainingArgs, worktree: ensured };
+}