vde-worktree 0.0.19 → 0.0.21

package/dist/index.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
 import { constants } from "node:fs";
-import { access, appendFile, chmod, cp, mkdir, open, readFile, readdir, rename, rm, symlink, writeFile } from "node:fs/promises";
+import { access, appendFile, chmod, cp, lstat, mkdir, open, readFile, readdir, realpath, rename, rm, symlink, writeFile } from "node:fs/promises";
 import { homedir, hostname } from "node:os";
 import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -10,6 +10,7 @@ import { parseArgs } from "citty";
 import { execa } from "execa";
 import stringWidth from "string-width";
 import { getBorderCharacters, table } from "table";
+import { parse } from "yaml";
 import { createHash } from "node:crypto";
 
 //#region src/core/constants.ts
@@ -74,6 +75,7 @@ const WRITE_COMMANDS = new Set([
 const ERROR_CODE_TO_EXIT_CODE = {
 	NOT_GIT_REPOSITORY: EXIT_CODE.NOT_GIT_REPOSITORY,
 	INVALID_ARGUMENT: EXIT_CODE.INVALID_ARGUMENT,
+	INVALID_CONFIG: EXIT_CODE.INVALID_ARGUMENT,
 	UNKNOWN_COMMAND: EXIT_CODE.INVALID_ARGUMENT,
 	UNSAFE_FLAG_REQUIRED: EXIT_CODE.SAFETY_REJECTED,
 	NOT_INITIALIZED: EXIT_CODE.SAFETY_REJECTED,
@@ -130,6 +132,678 @@ const ensureCliError = (error) => {
 	});
 };
 
+//#endregion
+//#region src/config/git-boundary.ts
+const hasGitMarker = async (directory) => {
+	try {
+		const stat = await lstat(join(directory, ".git"));
+		return stat.isDirectory() || stat.isFile();
+	} catch {
+		return false;
+	}
+};
+const findGitBoundaryDirectory = async (cwd) => {
+	let current = resolve(cwd);
+	while (true) {
+		if (await hasGitMarker(current)) return current;
+		const parent = dirname(current);
+		if (parent === current) return null;
+		current = parent;
+	}
+};
+const collectConfigSearchDirectories = async (cwd) => {
+	const absoluteCwd = resolve(cwd);
+	const boundary = await findGitBoundaryDirectory(absoluteCwd);
+	if (boundary === null) return [absoluteCwd];
+	const directories = [];
+	let current = absoluteCwd;
+	while (true) {
+		directories.push(current);
+		if (current === boundary) break;
+		const parent = dirname(current);
+		if (parent === current) break;
+		current = parent;
+	}
+	return directories.reverse();
+};
+
+//#endregion
+//#region src/config/types.ts
+const LIST_TABLE_COLUMNS = [
+	"branch",
+	"dirty",
+	"merged",
+	"pr",
+	"locked",
+	"ahead",
+	"behind",
+	"path"
+];
+const LIST_PATH_TRUNCATE_VALUES = ["auto", "never"];
+const SELECTOR_CD_SURFACE_VALUES = [
+	"auto",
+	"inline",
+	"tmux-popup"
+];
+const DEFAULT_CONFIG = {
+	paths: { worktreeRoot: ".worktree" },
+	git: {
+		baseBranch: null,
+		baseRemote: "origin"
+	},
+	github: { enabled: true },
+	hooks: {
+		enabled: true,
+		timeoutMs: DEFAULT_HOOK_TIMEOUT_MS
+	},
+	locks: {
+		timeoutMs: DEFAULT_LOCK_TIMEOUT_MS,
+		staleLockTTLSeconds: DEFAULT_STALE_LOCK_TTL_SECONDS
+	},
+	list: { table: {
+		columns: [...LIST_TABLE_COLUMNS],
+		path: {
+			truncate: "auto",
+			minWidth: 12
+		}
+	} },
+	selector: { cd: {
+		prompt: "worktree> ",
+		surface: "auto",
+		tmuxPopupOpts: "80%,70%",
+		fzf: { extraArgs: [] }
+	} }
+};
+
+//#endregion
+//#region src/config/loader.ts
+const CONFIG_FILE_BASENAME = "config.yml";
+const LOCAL_CONFIG_PATH_SEGMENTS = [
+	".vde",
+	"worktree",
+	CONFIG_FILE_BASENAME
+];
+const GLOBAL_CONFIG_PATH_SEGMENTS = [
+	"vde",
+	"worktree",
+	CONFIG_FILE_BASENAME
+];
+const isRecord = (value) => {
+	return value !== null && typeof value === "object" && Array.isArray(value) !== true;
+};
+const toKeyPath = (segments) => {
+	if (segments.length === 0) return "<root>";
+	return segments.join(".");
+};
+const throwInvalidConfig = ({ file, keyPath, reason }) => {
+	throw createCliError("INVALID_CONFIG", {
+		message: `Invalid config: ${file} (${keyPath}: ${reason})`,
+		details: {
+			file,
+			keyPath,
+			reason
+		}
+	});
+};
+const expectRecord = ({ value, ctx, keyPath }) => {
+	if (isRecord(value)) return value;
+	return throwInvalidConfig({
+		file: ctx.file,
+		keyPath: toKeyPath(keyPath),
+		reason: "must be an object"
+	});
+};
+const ensureNoUnknownKeys = ({ record, allowedKeys, ctx, keyPath }) => {
+	const allowed = new Set(allowedKeys);
+	for (const key of Object.keys(record)) {
+		if (allowed.has(key)) continue;
+		const path = [...keyPath, key];
+		throwInvalidConfig({
+			file: ctx.file,
+			keyPath: toKeyPath(path),
+			reason: "unknown key"
+		});
+	}
+};
+const parseBoolean = ({ value, ctx, keyPath }) => {
+	if (typeof value === "boolean") return value;
+	return throwInvalidConfig({
+		file: ctx.file,
+		keyPath: toKeyPath(keyPath),
+		reason: "must be boolean"
+	});
+};
+const parseNonEmptyString = ({ value, ctx, keyPath }) => {
+	if (typeof value === "string" && value.trim().length > 0) return value;
+	return throwInvalidConfig({
+		file: ctx.file,
+		keyPath: toKeyPath(keyPath),
+		reason: "must be a non-empty string"
+	});
+};
+const parsePositiveInteger = ({ value, ctx, keyPath }) => {
+	if (typeof value === "number" && Number.isInteger(value) && value > 0) return value;
+	return throwInvalidConfig({
+		file: ctx.file,
+		keyPath: toKeyPath(keyPath),
+		reason: "must be a positive integer"
+	});
+};
+const parseStringArray = ({ value, ctx, keyPath }) => {
+	if (Array.isArray(value) !== true) return throwInvalidConfig({
+		file: ctx.file,
+		keyPath: toKeyPath(keyPath),
+		reason: "must be an array"
+	});
+	const values = value;
+	const result = [];
+	for (const [index, item] of values.entries()) {
+		if (typeof item !== "string" || item.length === 0) throwInvalidConfig({
+			file: ctx.file,
+			keyPath: toKeyPath([...keyPath, String(index)]),
+			reason: "must be a non-empty string"
+		});
+		result.push(item);
+	}
+	return result;
+};
+const parseColumns = ({ value, ctx, keyPath }) => {
+	if (Array.isArray(value) !== true) return throwInvalidConfig({
+		file: ctx.file,
+		keyPath: toKeyPath(keyPath),
+		reason: "must be an array"
+	});
+	const values = value;
+	if (values.length === 0) return throwInvalidConfig({
+		file: ctx.file,
+		keyPath: toKeyPath(keyPath),
+		reason: "must not be empty"
+	});
+	const allowed = new Set(LIST_TABLE_COLUMNS);
+	const seen = /* @__PURE__ */ new Set();
+	const parsed = [];
+	for (const [index, item] of values.entries()) {
+		if (typeof item !== "string") throwInvalidConfig({
+			file: ctx.file,
+			keyPath: toKeyPath([...keyPath, String(index)]),
+			reason: "must be a string"
+		});
+		if (allowed.has(item) !== true) throwInvalidConfig({
+			file: ctx.file,
+			keyPath: toKeyPath([...keyPath, String(index)]),
+			reason: `unsupported column: ${item}`
+		});
+		if (seen.has(item)) throwInvalidConfig({
+			file: ctx.file,
+			keyPath: toKeyPath([...keyPath, String(index)]),
+			reason: `duplicate column: ${item}`
+		});
+		seen.add(item);
+		parsed.push(item);
+	}
+	return parsed;
+};
+const parseListPathTruncate = ({ value, ctx, keyPath }) => {
+	if (typeof value !== "string" || LIST_PATH_TRUNCATE_VALUES.includes(value) !== true) throwInvalidConfig({
+		file: ctx.file,
+		keyPath: toKeyPath(keyPath),
+		reason: `must be one of: ${LIST_PATH_TRUNCATE_VALUES.join(", ")}`
+	});
+	return value;
+};
+const parseSelectorSurface = ({ value, ctx, keyPath }) => {
+	if (typeof value !== "string" || SELECTOR_CD_SURFACE_VALUES.includes(value) !== true) throwInvalidConfig({
+		file: ctx.file,
+		keyPath: toKeyPath(keyPath),
+		reason: `must be one of: ${SELECTOR_CD_SURFACE_VALUES.join(", ")}`
+	});
+	return value;
+};
+const validatePartialConfig = ({ rawConfig, ctx }) => {
+	if (rawConfig === null || rawConfig === void 0) return {};
+	const root = expectRecord({
+		value: rawConfig,
+		ctx,
+		keyPath: []
+	});
+	ensureNoUnknownKeys({
+		record: root,
+		allowedKeys: [
+			"paths",
+			"git",
+			"github",
+			"hooks",
+			"locks",
+			"list",
+			"selector"
+		],
+		ctx,
+		keyPath: []
+	});
+	const partial = {};
+	if (root.paths !== void 0) {
+		const paths = expectRecord({
+			value: root.paths,
+			ctx,
+			keyPath: ["paths"]
+		});
+		ensureNoUnknownKeys({
+			record: paths,
+			allowedKeys: ["worktreeRoot"],
+			ctx,
+			keyPath: ["paths"]
+		});
+		partial.paths = {};
+		if (paths.worktreeRoot !== void 0) partial.paths.worktreeRoot = parseNonEmptyString({
+			value: paths.worktreeRoot,
+			ctx,
+			keyPath: ["paths", "worktreeRoot"]
+		});
+	}
+	if (root.git !== void 0) {
+		const git = expectRecord({
+			value: root.git,
+			ctx,
+			keyPath: ["git"]
+		});
+		ensureNoUnknownKeys({
+			record: git,
+			allowedKeys: ["baseBranch", "baseRemote"],
+			ctx,
+			keyPath: ["git"]
+		});
+		partial.git = {};
+		if (git.baseBranch !== void 0) {
+			if (git.baseBranch !== null && typeof git.baseBranch !== "string") throwInvalidConfig({
+				file: ctx.file,
+				keyPath: toKeyPath(["git", "baseBranch"]),
+				reason: "must be a string or null"
+			});
+			partial.git.baseBranch = git.baseBranch === null ? null : parseNonEmptyString({
+				value: git.baseBranch,
+				ctx,
+				keyPath: ["git", "baseBranch"]
+			});
+		}
+		if (git.baseRemote !== void 0) partial.git.baseRemote = parseNonEmptyString({
+			value: git.baseRemote,
+			ctx,
+			keyPath: ["git", "baseRemote"]
+		});
+	}
+	if (root.github !== void 0) {
+		const github = expectRecord({
+			value: root.github,
+			ctx,
+			keyPath: ["github"]
+		});
+		ensureNoUnknownKeys({
+			record: github,
+			allowedKeys: ["enabled"],
+			ctx,
+			keyPath: ["github"]
+		});
+		partial.github = {};
+		if (github.enabled !== void 0) partial.github.enabled = parseBoolean({
+			value: github.enabled,
+			ctx,
+			keyPath: ["github", "enabled"]
+		});
+	}
+	if (root.hooks !== void 0) {
+		const hooks = expectRecord({
+			value: root.hooks,
+			ctx,
+			keyPath: ["hooks"]
+		});
+		ensureNoUnknownKeys({
+			record: hooks,
+			allowedKeys: ["enabled", "timeoutMs"],
+			ctx,
+			keyPath: ["hooks"]
+		});
+		partial.hooks = {};
+		if (hooks.enabled !== void 0) partial.hooks.enabled = parseBoolean({
+			value: hooks.enabled,
+			ctx,
+			keyPath: ["hooks", "enabled"]
+		});
+		if (hooks.timeoutMs !== void 0) partial.hooks.timeoutMs = parsePositiveInteger({
+			value: hooks.timeoutMs,
+			ctx,
+			keyPath: ["hooks", "timeoutMs"]
+		});
+	}
+	if (root.locks !== void 0) {
+		const locks = expectRecord({
+			value: root.locks,
+			ctx,
+			keyPath: ["locks"]
+		});
+		ensureNoUnknownKeys({
+			record: locks,
+			allowedKeys: ["timeoutMs", "staleLockTTLSeconds"],
+			ctx,
+			keyPath: ["locks"]
+		});
+		partial.locks = {};
+		if (locks.timeoutMs !== void 0) partial.locks.timeoutMs = parsePositiveInteger({
+			value: locks.timeoutMs,
+			ctx,
+			keyPath: ["locks", "timeoutMs"]
+		});
+		if (locks.staleLockTTLSeconds !== void 0) partial.locks.staleLockTTLSeconds = parsePositiveInteger({
+			value: locks.staleLockTTLSeconds,
+			ctx,
+			keyPath: ["locks", "staleLockTTLSeconds"]
+		});
+	}
+	if (root.list !== void 0) {
+		const list = expectRecord({
+			value: root.list,
+			ctx,
+			keyPath: ["list"]
+		});
+		ensureNoUnknownKeys({
+			record: list,
+			allowedKeys: ["table"],
+			ctx,
+			keyPath: ["list"]
+		});
+		partial.list = {};
+		if (list.table !== void 0) {
+			const table = expectRecord({
+				value: list.table,
+				ctx,
+				keyPath: ["list", "table"]
+			});
+			ensureNoUnknownKeys({
+				record: table,
+				allowedKeys: ["columns", "path"],
+				ctx,
+				keyPath: ["list", "table"]
+			});
+			partial.list.table = {};
+			if (table.columns !== void 0) partial.list.table.columns = parseColumns({
+				value: table.columns,
+				ctx,
+				keyPath: [
+					"list",
+					"table",
+					"columns"
+				]
+			});
+			if (table.path !== void 0) {
+				const pathConfig = expectRecord({
+					value: table.path,
+					ctx,
+					keyPath: [
+						"list",
+						"table",
+						"path"
+					]
+				});
+				ensureNoUnknownKeys({
+					record: pathConfig,
+					allowedKeys: ["truncate", "minWidth"],
+					ctx,
+					keyPath: [
+						"list",
+						"table",
+						"path"
+					]
+				});
+				partial.list.table.path = {};
+				if (pathConfig.truncate !== void 0) partial.list.table.path.truncate = parseListPathTruncate({
+					value: pathConfig.truncate,
+					ctx,
+					keyPath: [
+						"list",
+						"table",
+						"path",
+						"truncate"
+					]
+				});
+				if (pathConfig.minWidth !== void 0) {
+					const minWidth = parsePositiveInteger({
+						value: pathConfig.minWidth,
+						ctx,
+						keyPath: [
+							"list",
+							"table",
+							"path",
+							"minWidth"
+						]
+					});
+					if (minWidth < 8 || minWidth > 200) throwInvalidConfig({
+						file: ctx.file,
+						keyPath: toKeyPath([
+							"list",
+							"table",
+							"path",
+							"minWidth"
+						]),
+						reason: "must be in range 8..200"
+					});
+					partial.list.table.path.minWidth = minWidth;
+				}
+			}
+		}
+	}
+	if (root.selector !== void 0) {
+		const selector = expectRecord({
+			value: root.selector,
+			ctx,
+			keyPath: ["selector"]
+		});
+		ensureNoUnknownKeys({
+			record: selector,
+			allowedKeys: ["cd"],
+			ctx,
+			keyPath: ["selector"]
+		});
+		partial.selector = {};
+		if (selector.cd !== void 0) {
+			const cd = expectRecord({
+				value: selector.cd,
+				ctx,
+				keyPath: ["selector", "cd"]
+			});
+			ensureNoUnknownKeys({
+				record: cd,
+				allowedKeys: [
+					"prompt",
+					"surface",
+					"tmuxPopupOpts",
+					"fzf"
+				],
+				ctx,
+				keyPath: ["selector", "cd"]
+			});
+			partial.selector.cd = {};
+			if (cd.prompt !== void 0) partial.selector.cd.prompt = parseNonEmptyString({
+				value: cd.prompt,
+				ctx,
+				keyPath: [
+					"selector",
+					"cd",
+					"prompt"
+				]
+			});
+			if (cd.surface !== void 0) partial.selector.cd.surface = parseSelectorSurface({
+				value: cd.surface,
+				ctx,
+				keyPath: [
+					"selector",
+					"cd",
+					"surface"
+				]
+			});
+			if (cd.tmuxPopupOpts !== void 0) partial.selector.cd.tmuxPopupOpts = parseNonEmptyString({
+				value: cd.tmuxPopupOpts,
+				ctx,
+				keyPath: [
+					"selector",
+					"cd",
+					"tmuxPopupOpts"
+				]
+			});
+			if (cd.fzf !== void 0) {
+				const fzf = expectRecord({
+					value: cd.fzf,
+					ctx,
+					keyPath: [
+						"selector",
+						"cd",
+						"fzf"
+					]
+				});
+				ensureNoUnknownKeys({
+					record: fzf,
+					allowedKeys: ["extraArgs"],
+					ctx,
+					keyPath: [
+						"selector",
+						"cd",
+						"fzf"
+					]
+				});
+				partial.selector.cd.fzf = {};
+				if (fzf.extraArgs !== void 0) partial.selector.cd.fzf.extraArgs = parseStringArray({
+					value: fzf.extraArgs,
+					ctx,
+					keyPath: [
+						"selector",
+						"cd",
+						"fzf",
+						"extraArgs"
+					]
+				});
+			}
+		}
+	}
+	return partial;
+};
+const mergeConfig = (base, partial) => {
+	return {
+		paths: { worktreeRoot: partial.paths?.worktreeRoot ?? base.paths.worktreeRoot },
+		git: {
+			baseBranch: partial.git?.baseBranch === void 0 ? base.git.baseBranch : partial.git.baseBranch,
+			baseRemote: partial.git?.baseRemote ?? base.git.baseRemote
+		},
+		github: { enabled: partial.github?.enabled ?? base.github.enabled },
+		hooks: {
+			enabled: partial.hooks?.enabled ?? base.hooks.enabled,
+			timeoutMs: partial.hooks?.timeoutMs ?? base.hooks.timeoutMs
+		},
+		locks: {
+			timeoutMs: partial.locks?.timeoutMs ?? base.locks.timeoutMs,
+			staleLockTTLSeconds: partial.locks?.staleLockTTLSeconds ?? base.locks.staleLockTTLSeconds
+		},
+		list: { table: {
+			columns: partial.list?.table?.columns ? [...partial.list.table.columns] : [...base.list.table.columns],
+			path: {
+				truncate: partial.list?.table?.path?.truncate ?? base.list.table.path.truncate,
+				minWidth: partial.list?.table?.path?.minWidth ?? base.list.table.path.minWidth
+			}
+		} },
+		selector: { cd: {
+			prompt: partial.selector?.cd?.prompt ?? base.selector.cd.prompt,
+			surface: partial.selector?.cd?.surface ?? base.selector.cd.surface,
+			tmuxPopupOpts: partial.selector?.cd?.tmuxPopupOpts ?? base.selector.cd.tmuxPopupOpts,
+			fzf: { extraArgs: partial.selector?.cd?.fzf?.extraArgs ? [...partial.selector.cd.fzf.extraArgs] : [...base.selector.cd.fzf.extraArgs] }
+		} }
+	};
+};
+const configPathExists = async (filePath) => {
+	try {
+		await access(filePath, constants.F_OK);
+		return true;
+	} catch {
+		return false;
+	}
+};
+const resolveLocalConfigPath = (directory) => {
+	return join(directory, ...LOCAL_CONFIG_PATH_SEGMENTS);
+};
+const resolveGlobalConfigPath = () => {
+	const xdgConfigHome = process.env.XDG_CONFIG_HOME;
+	if (typeof xdgConfigHome === "string" && xdgConfigHome.length > 0) return join(resolve(xdgConfigHome), ...GLOBAL_CONFIG_PATH_SEGMENTS);
+	return join(homedir(), ".config", ...GLOBAL_CONFIG_PATH_SEGMENTS);
+};
+const resolveExistingConfigFiles = async ({ cwd, repoRoot }) => {
+	const localCandidates = (await collectConfigSearchDirectories(cwd)).map((directory) => resolveLocalConfigPath(directory));
+	const repoRootCandidate = resolveLocalConfigPath(repoRoot);
+	const lowToHighCandidates = [
+		resolveGlobalConfigPath(),
+		repoRootCandidate,
+		...localCandidates
+	];
+	const deduped = /* @__PURE__ */ new Map();
+	for (const [order, candidate] of lowToHighCandidates.entries()) {
+		if (await configPathExists(candidate) !== true) continue;
+		const canonical = await realpath(candidate).catch(() => resolve(candidate));
+		deduped.set(canonical, {
+			path: candidate,
+			order
+		});
+	}
+	return [...deduped.values()].sort((a, b) => a.order - b.order).map((entry) => entry.path);
+};
+const validateWorktreeRoot = async ({ repoRoot, config }) => {
+	const rawWorktreeRoot = config.paths.worktreeRoot;
+	const resolvedWorktreeRoot = isAbsolute(rawWorktreeRoot) ? resolve(rawWorktreeRoot) : resolve(repoRoot, rawWorktreeRoot);
+	try {
+		if ((await lstat(resolvedWorktreeRoot)).isDirectory() !== true) throwInvalidConfig({
+			file: "<resolved>",
+			keyPath: "paths.worktreeRoot",
+			reason: "must not point to an existing file"
+		});
+	} catch (error) {
+		if (error.code === "ENOENT") return;
+		throw error;
+	}
+};
+const parseConfigFile = async (file) => {
+	const rawContent = await readFile(file, "utf8");
+	let parsed;
+	try {
+		parsed = parse(rawContent);
+	} catch (error) {
+		throwInvalidConfig({
+			file,
+			keyPath: "<root>",
+			reason: error instanceof Error ? error.message : String(error)
+		});
+	}
+	return validatePartialConfig({
+		rawConfig: parsed,
+		ctx: { file }
+	});
+};
+const cloneDefaultConfig = () => {
+	return mergeConfig(DEFAULT_CONFIG, {});
+};
+const loadResolvedConfig = async ({ cwd, repoRoot }) => {
+	const files = await resolveExistingConfigFiles({
+		cwd,
+		repoRoot
+	});
+	let config = cloneDefaultConfig();
+	for (const file of files) {
+		const partial = await parseConfigFile(file);
+		config = mergeConfig(config, partial);
+	}
+	await validateWorktreeRoot({
+		repoRoot,
+		config
+	});
+	return {
+		config,
+		loadedFiles: files
+	};
+};
+
 //#endregion
 //#region src/git/exec.ts
 const runGitCommand = async ({ cwd, args, reject = true }) => {
@@ -175,6 +849,7 @@ const doesGitRefExist = async (cwd, ref) => {
 //#endregion
 //#region src/core/paths.ts
 const GIT_DIR_NAME = ".git";
+const DEFAULT_WORKTREE_ROOT = ".worktree";
 const WORKTREE_ID_HASH_LENGTH = 12;
 const WORKTREE_ID_SLUG_MAX_LENGTH = 48;
 const resolveRepoRootFromCommonDir = ({ currentWorktreeRoot, gitCommonDir }) => {
@@ -212,8 +887,9 @@ const resolveRepoContext = async (cwd) => {
 		gitCommonDir
 	};
 };
-const getWorktreeRootPath = (repoRoot) => {
-	return join(repoRoot, ".worktree");
+const getWorktreeRootPath = (repoRoot, configuredWorktreeRoot = DEFAULT_WORKTREE_ROOT) => {
+	if (isAbsolute(configuredWorktreeRoot)) return resolve(configuredWorktreeRoot);
+	return resolve(repoRoot, configuredWorktreeRoot);
 };
 const getWorktreeMetaRootPath = (repoRoot) => {
 	return join(repoRoot, ".vde", "worktree");
@@ -233,25 +909,33 @@ const getStateDirectoryPath = (repoRoot) => {
 const branchToWorktreeId = (branch) => {
 	return `${branch.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, WORKTREE_ID_SLUG_MAX_LENGTH) || "branch"}--${createHash("sha256").update(branch).digest("hex").slice(0, WORKTREE_ID_HASH_LENGTH)}`;
 };
-const branchToWorktreePath = (repoRoot, branch) => {
-	const worktreeRoot = getWorktreeRootPath(repoRoot);
-	return ensurePathInsideRepo({
-		repoRoot: worktreeRoot,
-		path: join(worktreeRoot, ...branch.split("/"))
+const branchToWorktreePath = (repoRoot, branch, configuredWorktreeRoot = DEFAULT_WORKTREE_ROOT) => {
+	const worktreeRoot = getWorktreeRootPath(repoRoot, configuredWorktreeRoot);
+	return ensurePathInsideRoot({
+		rootPath: worktreeRoot,
+		path: join(worktreeRoot, ...branch.split("/")),
+		message: "Path is outside managed worktree root"
 	});
 };
-const ensurePathInsideRepo = ({ repoRoot, path }) => {
-	const rel = relative(repoRoot, path);
+const ensurePathInsideRoot = ({ rootPath, path, message = "Path is outside allowed root" }) => {
+	const rel = relative(rootPath, path);
 	if (rel === "") return path;
 	if (rel === ".." || rel.startsWith(`..${sep}`)) throw createCliError("PATH_OUTSIDE_REPO", {
-		message: "Path is outside repository root",
+		message,
 		details: {
-			repoRoot,
+			rootPath,
 			path
 		}
 	});
 	return path;
 };
+const ensurePathInsideRepo = ({ repoRoot, path }) => {
+	return ensurePathInsideRoot({
+		rootPath: repoRoot,
+		path,
+		message: "Path is outside repository root"
+	});
+};
 const resolveRepoRelativePath = ({ repoRoot, relativePath }) => {
 	if (isAbsolute(relativePath)) throw createCliError("ABSOLUTE_PATH_NOT_ALLOWED", {
 		message: "Absolute path is not allowed",
@@ -266,6 +950,11 @@ const resolvePathFromCwd = ({ cwd, path }) => {
 	if (isAbsolute(path)) return path;
 	return resolve(cwd, path);
 };
+const isManagedWorktreePath = ({ worktreePath, managedWorktreeRoot }) => {
+	const rel = relative(managedWorktreeRoot, worktreePath);
+	if (rel === "" || rel === "." || rel === "..") return false;
+	return rel.startsWith(`..${sep}`) !== true;
+};
 
 //#endregion
 //#region src/core/hooks.ts
@@ -287,11 +976,10 @@ const appendHookLog = async ({ repoRoot, action, branch, content }) => {
 		branch
 	})), content, "utf8");
 };
-const runHook = async ({ phase, hookName, args, context, requireExists = false }) => {
-	if (context.enabled !== true) return;
-	const path = hookPath(context.repoRoot, hookName);
+const ensureHookExists = async ({ path, hookName, requireExists }) => {
 	try {
 		await access(path, constants.F_OK);
+		return true;
 	} catch {
 		if (requireExists) throw createCliError("HOOK_NOT_FOUND", {
 			message: `Hook not found: ${hookName}`,
@@ -300,8 +988,10 @@ const runHook = async ({ phase, hookName, args, context, requireExists = false }
 				path
 			}
 		});
-		return;
+		return false;
 	}
+};
+const ensureHookExecutable = async ({ path, hookName }) => {
 	try {
 		await access(path, constants.X_OK);
 	} catch {
@@ -313,43 +1003,102 @@ const runHook = async ({ phase, hookName, args, context, requireExists = false }
 			}
 		});
 	}
+};
+const executeHookProcess = async ({ path, args, context }) => {
 	const startedAt = (/* @__PURE__ */ new Date()).toISOString();
-	try {
-		const result = await execa(path, [...args], {
-			cwd: context.worktreePath ?? context.repoRoot,
-			env: {
-				...process.env,
-				WT_REPO_ROOT: context.repoRoot,
-				WT_ACTION: context.action,
-				WT_BRANCH: context.branch ?? "",
-				WT_WORKTREE_PATH: context.worktreePath ?? "",
-				WT_IS_TTY: process.stdout.isTTY === true ? "1" : "0",
-				WT_TOOL: "vde-worktree",
-				...context.extraEnv ?? {}
-			},
-			timeout: context.timeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS,
-			reject: false
-		});
-		const endedAt = (/* @__PURE__ */ new Date()).toISOString();
-		const logContent = [
+	const result = await execa(path, [...args], {
+		cwd: context.worktreePath ?? context.repoRoot,
+		env: {
+			...process.env,
+			WT_REPO_ROOT: context.repoRoot,
+			WT_ACTION: context.action,
+			WT_BRANCH: context.branch ?? "",
+			WT_WORKTREE_PATH: context.worktreePath ?? "",
+			WT_IS_TTY: process.stdout.isTTY === true ? "1" : "0",
+			WT_TOOL: "vde-worktree",
+			...context.extraEnv ?? {}
+		},
+		timeout: context.timeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS,
+		reject: false
+	});
+	const endedAt = (/* @__PURE__ */ new Date()).toISOString();
+	return {
+		exitCode: result.exitCode ?? 0,
+		stderr: result.stderr ?? "",
+		timedOut: result.timedOut === true,
+		startedAt,
+		endedAt
+	};
+};
+const writeHookLog = async ({ repoRoot, action, branch, hookName, phase, result }) => {
+	await appendHookLog({
+		repoRoot,
+		action,
+		branch,
+		content: [
 			`hook=${hookName}`,
 			`phase=${phase}`,
-			`start=${startedAt}`,
-			`end=${endedAt}`,
-			`exitCode=${String(result.exitCode ?? 0)}`,
-			`stderr=${result.stderr ?? ""}`,
+			`start=${result.startedAt}`,
+			`end=${result.endedAt}`,
+			`exitCode=${String(result.exitCode)}`,
+			`timedOut=${result.timedOut ? "1" : "0"}`,
+			`stderr=${result.stderr}`,
 			""
-		].join("\n");
-		await appendHookLog({
+		].join("\n")
+	});
+};
+const shouldIgnorePostHookFailure = ({ phase, context }) => {
+	return phase === "post" && context.strictPostHooks !== true;
+};
+const handleIgnoredPostHookFailure = ({ context, hookName, message }) => {
+	context.stderr(message ?? `Hook failed: ${hookName}`);
+};
+const runHook = async ({ phase, hookName, args, context, requireExists = false }) => {
+	if (context.enabled !== true) return;
+	const path = hookPath(context.repoRoot, hookName);
+	if (await ensureHookExists({
+		path,
+		hookName,
+		requireExists
+	}) !== true) return;
+	await ensureHookExecutable({
+		path,
+		hookName
+	});
+	try {
+		const result = await executeHookProcess({
+			path,
+			args,
+			context
+		});
+		await writeHookLog({
 			repoRoot: context.repoRoot,
 			action: context.action,
 			branch: context.branch,
-			content: logContent
+			hookName,
+			phase,
+			result
 		});
-		if ((result.exitCode ?? 0) === 0) return;
-		const message = `Hook failed: ${hookName} (exitCode=${String(result.exitCode ?? 1)})`;
-		if (phase === "post" && context.strictPostHooks !== true) {
-			context.stderr(message);
+		if (result.timedOut) throw createCliError("HOOK_TIMEOUT", {
+			message: `Hook timed out: ${hookName}`,
+			details: {
+				hook: hookName,
+				timeoutMs: context.timeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS,
+				exitCode: result.exitCode,
+				stderr: result.stderr
+			}
+		});
+		if (result.exitCode === 0) return;
+		const message = `Hook failed: ${hookName} (exitCode=${String(result.exitCode)})`;
+		if (shouldIgnorePostHookFailure({
+			phase,
+			context
+		})) {
+			handleIgnoredPostHookFailure({
+				context,
+				hookName,
+				message
+			});
 			return;
 		}
 		throw createCliError("HOOK_FAILED", {
@@ -372,8 +1121,14 @@ const runHook = async ({ phase, hookName, args, context, requireExists = false }
 			},
 			cause: error
 		});
-		if (phase === "post" && context.strictPostHooks !== true) {
-			context.stderr(`Hook failed: ${hookName}`);
+		if (shouldIgnorePostHookFailure({
+			phase,
+			context
+		})) {
+			handleIgnoredPostHookFailure({
+				context,
+				hookName
+			});
 			return;
 		}
 		throw createCliError("HOOK_FAILED", {
@@ -414,7 +1169,7 @@ const invokeHook = async ({ hookName, args, context }) => {
 
 //#endregion
 //#region src/core/init.ts
-const MANAGED_EXCLUDE_BLOCK = `# vde-worktree (managed)\n.worktree/\n.vde/worktree/\n`;
+const EXCLUDE_MARKER = "# vde-worktree (managed)";
 const DEFAULT_HOOKS = [{
 	name: "post-new",
 	lines: [
@@ -448,7 +1203,27 @@ const createHookTemplate = async (hooksDir, name, lines) => {
 		await chmod(targetPath, 493);
 	}
 };
-const ensureExcludeBlock = async (repoRoot) => {
+const isPathInsideOrEqual = ({ rootPath, candidatePath }) => {
+	const rel = relative(rootPath, candidatePath);
+	if (rel.length === 0) return true;
+	return rel !== ".." && rel.startsWith(`..${sep}`) !== true;
+};
+const toExcludeEntry = ({ repoRoot, managedWorktreeRoot }) => {
+	if (isPathInsideOrEqual({
+		rootPath: repoRoot,
+		candidatePath: managedWorktreeRoot
+	}) !== true) return null;
+	const rel = relative(repoRoot, managedWorktreeRoot).split(sep).join("/");
+	const normalized = rel.length === 0 ? "." : rel;
+	return normalized.endsWith("/") ? normalized : `${normalized}/`;
+};
+const ensureExcludeBlock = async ({ repoRoot, managedWorktreeRoot }) => {
+	const managedEntry = toExcludeEntry({
+		repoRoot,
+		managedWorktreeRoot
+	});
+	if (managedEntry === null) return;
+	const managedExcludeBlock = `${EXCLUDE_MARKER}\n${managedEntry}\n.vde/worktree/\n`;
 	const excludePath = join(repoRoot, ".git", "info", "exclude");
 	let current = "";
 	try {
@@ -456,8 +1231,8 @@ const ensureExcludeBlock = async (repoRoot) => {
 	} catch {
 		current = "";
 	}
-	if (current.includes(MANAGED_EXCLUDE_BLOCK)) return;
-	await writeFile(excludePath, `${current.endsWith("\n") || current.length === 0 ? current : `${current}\n`}${MANAGED_EXCLUDE_BLOCK}`, "utf8");
+	if (current.includes(managedExcludeBlock)) return;
+	await writeFile(excludePath, `${current.endsWith("\n") || current.length === 0 ? current : `${current}\n`}${managedExcludeBlock}`, "utf8");
 };
 const isInitialized = async (repoRoot) => {
 	try {
@@ -467,18 +1242,94 @@ const isInitialized = async (repoRoot) => {
 		return false;
 	}
 };
-const initializeRepository = async (repoRoot) => {
+const initializeRepository = async ({ repoRoot, managedWorktreeRoot }) => {
 	const wasInitialized = await isInitialized(repoRoot);
-	await mkdir(getWorktreeRootPath(repoRoot), { recursive: true });
+	await mkdir(managedWorktreeRoot, { recursive: true });
 	await mkdir(getHooksDirectoryPath(repoRoot), { recursive: true });
 	await mkdir(getLogsDirectoryPath(repoRoot), { recursive: true });
 	await mkdir(getLocksDirectoryPath(repoRoot), { recursive: true });
 	await mkdir(getStateDirectoryPath(repoRoot), { recursive: true });
-	await ensureExcludeBlock(repoRoot);
+	await ensureExcludeBlock({
+		repoRoot,
+		managedWorktreeRoot
+	});
 	for (const hook of DEFAULT_HOOKS) await createHookTemplate(getHooksDirectoryPath(repoRoot), hook.name, hook.lines);
 	return { alreadyInitialized: wasInitialized };
 };
 
+//#endregion
+//#region src/core/json-storage.ts
+const parseJsonRecord = ({ content, schemaVersion, validate }) => {
+	try {
+		const parsed = JSON.parse(content);
+		if (parsed.schemaVersion !== schemaVersion || validate(parsed) !== true) return {
+			valid: false,
+			record: null
+		};
+		return {
+			valid: true,
+			record: parsed
+		};
+	} catch {
+		return {
+			valid: false,
+			record: null
+		};
+	}
+};
+const readJsonRecord = async ({ path, schemaVersion, validate }) => {
+	try {
+		return {
+			path,
+			exists: true,
+			...parseJsonRecord({
+				content: await readFile(path, "utf8"),
+				schemaVersion,
+				validate
+			})
+		};
+	} catch (error) {
+		if (error.code === "ENOENT") return {
+			path,
+			exists: false,
+			valid: true,
+			record: null
+		};
+		return {
+			path,
+			exists: true,
+			valid: false,
+			record: null
+		};
+	}
+};
+const writeJsonAtomically = async ({ filePath, payload, ensureDir = false }) => {
+	if (ensureDir) await mkdir(dirname(filePath), { recursive: true });
+	const tmpPath = `${filePath}.tmp-${String(process.pid)}-${String(Date.now())}`;
+	try {
+		await writeFile(tmpPath, `${JSON.stringify(payload)}\n`, "utf8");
+		await rename(tmpPath, filePath);
+	} catch (error) {
+		try {
+			await rm(tmpPath, { force: true });
+		} catch {}
+		throw error;
+	}
+};
+const writeJsonExclusively = async ({ path, payload }) => {
+	let handle;
+	try {
+		handle = await open(path, "wx");
+		await handle.writeFile(`${JSON.stringify(payload)}\n`, "utf8");
+		return true;
+	} catch (error) {
+		if (error.code === "EEXIST") return false;
+		throw error;
+	} finally {
+		if (handle !== void 0) await handle.close();
+	}
+};
+
 //#endregion
 //#region src/core/repo-lock.ts
 const sleep = async (ms) => {
@@ -496,16 +1347,8 @@ const isProcessAlive = (pid) => {
 		return true;
 	}
 };
-const safeParseLockFile = (content) => {
-	try {
-		const parsed = JSON.parse(content);
-		if (parsed.schemaVersion !== 1) return null;
-		if (typeof parsed.command !== "string" || typeof parsed.owner !== "string") return null;
-		if (typeof parsed.pid !== "number" || typeof parsed.host !== "string" || typeof parsed.startedAt !== "string") return null;
-		return parsed;
-	} catch {
-		return null;
-	}
+const isRepoLockFileSchema = (parsed) => {
+	return typeof parsed.owner === "string" && typeof parsed.command === "string" && typeof parsed.pid === "number" && typeof parsed.host === "string" && typeof parsed.startedAt === "string";
 };
 const lockFilePath$1 = async (repoRoot) => {
 	const stateDir = getStateDirectoryPath(repoRoot);
@@ -534,23 +1377,15 @@ const canRecoverStaleLock = ({ lock, staleLockTTLSeconds }) => {
 	if (lock.host === hostname() && isProcessAlive(lock.pid)) return false;
 	return true;
 };
-const writeNewLockFile = async (path, payload) => {
-	try {
-		const handle = await open(path, "wx");
-		await handle.writeFile(`${JSON.stringify(payload)}\n`, "utf8");
-		await handle.close();
-		return true;
-	} catch (error) {
-		if (error.code === "EEXIST") return false;
-		throw error;
-	}
-};
 const acquireRepoLock = async ({ repoRoot, command, timeoutMs = DEFAULT_LOCK_TIMEOUT_MS, staleLockTTLSeconds = DEFAULT_STALE_LOCK_TTL_SECONDS }) => {
 	const path = await lockFilePath$1(repoRoot);
 	const startAt = Date.now();
 	const payload = buildLockPayload(command);
 	while (Date.now() - startAt <= timeoutMs) {
-		if (await writeNewLockFile(path, payload)) return { release: async () => {
+		if (await writeJsonExclusively({
+			path,
+			payload
+		})) return { release: async () => {
 			try {
 				await rm(path, { force: true });
 			} catch {
@@ -565,7 +1400,11 @@ const acquireRepoLock = async ({ repoRoot, command, timeoutMs = DEFAULT_LOCK_TIM
 			continue;
 		}
 		if (canRecoverStaleLock({
-			lock: safeParseLockFile(lockContent),
+			lock: parseJsonRecord({
+				content: lockContent,
+				schemaVersion: 1,
+				validate: isRepoLockFileSchema
+			}).record,
 			staleLockTTLSeconds
 		})) {
 			try {
@@ -614,57 +1453,16 @@ const hasStateDirectory = async (repoRoot) => {
 		return false;
 	}
 };
-const parseLifecycle = (content) => {
-	try {
-		const parsed = JSON.parse(content);
-		const isLastDivergedHeadValid = parsed.lastDivergedHead === null || typeof parsed.lastDivergedHead === "string" && parsed.lastDivergedHead.length > 0;
-		if (parsed.schemaVersion !== 2 || typeof parsed.branch !== "string" || typeof parsed.worktreeId !== "string" || typeof parsed.baseBranch !== "string" || typeof parsed.everDiverged !== "boolean" || isLastDivergedHeadValid !== true || typeof parsed.createdAt !== "string" || typeof parsed.updatedAt !== "string") return {
-			valid: false,
-			record: null
-		};
-		return {
-			valid: true,
-			record: parsed
-		};
-	} catch {
-		return {
-			valid: false,
-			record: null
-		};
-	}
-};
-const writeJsonAtomically$1 = async ({ filePath, payload }) => {
-	await mkdir(dirname(filePath), { recursive: true });
-	const tmpPath = `${filePath}.tmp-${String(process.pid)}-${String(Date.now())}`;
-	await writeFile(tmpPath, `${JSON.stringify(payload)}\n`, "utf8");
-	await rename(tmpPath, filePath);
+const isWorktreeMergeLifecycleRecord = (parsed) => {
+	const isLastDivergedHeadValid = parsed.lastDivergedHead === null || typeof parsed.lastDivergedHead === "string" && parsed.lastDivergedHead.length > 0;
+	return typeof parsed.branch === "string" && typeof parsed.worktreeId === "string" && typeof parsed.baseBranch === "string" && typeof parsed.everDiverged === "boolean" && isLastDivergedHeadValid && typeof parsed.createdAt === "string" && typeof parsed.updatedAt === "string";
 };
 const readWorktreeMergeLifecycle = async ({ repoRoot, branch }) => {
-	const path = lifecycleFilePath(repoRoot, branch);
-	try {
-		await access(path, constants.F_OK);
-	} catch {
-		return {
-			path,
-			exists: false,
-			valid: true,
-			record: null
-		};
-	}
-	try {
-		return {
-			path,
-			exists: true,
-			...parseLifecycle(await readFile(path, "utf8"))
-		};
-	} catch {
-		return {
-			path,
-			exists: true,
-			valid: false,
-			record: null
-		};
-	}
+	return readJsonRecord({
+		path: lifecycleFilePath(repoRoot, branch),
+		schemaVersion: 2,
+		validate: isWorktreeMergeLifecycleRecord
+	});
 };
 const upsertWorktreeMergeLifecycle = async ({ repoRoot, branch, baseBranch, observedDivergedHead }) => {
 	const normalizedObservedHead = typeof observedDivergedHead === "string" && observedDivergedHead.length > 0 ? observedDivergedHead : null;
@@ -699,9 +1497,10 @@ const upsertWorktreeMergeLifecycle = async ({ repoRoot, branch, baseBranch, obse
 		createdAt: current.record?.createdAt ?? now,
 		updatedAt: now
 	};
-	await writeJsonAtomically$1({
+	await writeJsonAtomically({
 		filePath: current.path,
-		payload: next
+		payload: next,
+		ensureDir: true
 	});
 	return next;
 };
@@ -738,71 +1537,32 @@ const moveWorktreeMergeLifecycle = async ({ repoRoot, fromBranch, toBranch, base
 		createdAt: source.record?.createdAt ?? now,
 		updatedAt: now
 	};
-	await writeJsonAtomically$1({
-		filePath: targetPath,
-		payload: next
-	});
-	if (source.path !== targetPath) await rm(source.path, { force: true });
-	return next;
-};
-const deleteWorktreeMergeLifecycle = async ({ repoRoot, branch }) => {
-	await rm(lifecycleFilePath(repoRoot, branch), { force: true });
-};
-
-//#endregion
-//#region src/core/worktree-lock.ts
-const parseLock = (content) => {
-	try {
-		const parsed = JSON.parse(content);
-		if (parsed.schemaVersion !== 1 || typeof parsed.branch !== "string" || typeof parsed.worktreeId !== "string" || typeof parsed.reason !== "string" || typeof parsed.owner !== "string" || typeof parsed.host !== "string" || typeof parsed.pid !== "number" || typeof parsed.createdAt !== "string" || typeof parsed.updatedAt !== "string") return {
-			valid: false,
-			record: null
-		};
-		return {
-			valid: true,
-			record: parsed
-		};
-	} catch {
-		return {
-			valid: false,
-			record: null
-		};
-	}
+	await writeJsonAtomically({
+		filePath: targetPath,
+		payload: next,
+		ensureDir: true
+	});
+	if (source.path !== targetPath) await rm(source.path, { force: true });
+	return next;
 };
-const writeJsonAtomically = async ({ filePath, payload }) => {
-	const tmpPath = `${filePath}.tmp-${String(process.pid)}-${String(Date.now())}`;
-	await writeFile(tmpPath, `${JSON.stringify(payload)}\n`, "utf8");
-	await rename(tmpPath, filePath);
+const deleteWorktreeMergeLifecycle = async ({ repoRoot, branch }) => {
+	await rm(lifecycleFilePath(repoRoot, branch), { force: true });
+};
+
+//#endregion
+//#region src/core/worktree-lock.ts
+const isWorktreeLockRecord = (parsed) => {
+	return parsed.schemaVersion === 1 && typeof parsed.branch === "string" && typeof parsed.worktreeId === "string" && typeof parsed.reason === "string" && typeof parsed.owner === "string" && typeof parsed.host === "string" && typeof parsed.pid === "number" && typeof parsed.createdAt === "string" && typeof parsed.updatedAt === "string";
 };
 const lockFilePath = (repoRoot, branch) => {
 	return join(getLocksDirectoryPath(repoRoot), `${branchToWorktreeId(branch)}.json`);
 };
 const readWorktreeLock = async ({ repoRoot, branch }) => {
-	const path = lockFilePath(repoRoot, branch);
-	try {
-		await access(path, constants.F_OK);
-	} catch {
-		return {
-			path,
-			exists: false,
-			valid: true,
-			record: null
-		};
-	}
-	try {
-		return {
-			path,
-			exists: true,
-			...parseLock(await readFile(path, "utf8"))
-		};
-	} catch {
-		return {
-			path,
-			exists: true,
-			valid: false,
-			record: null
-		};
-	}
+	return readJsonRecord({
+		path: lockFilePath(repoRoot, branch),
+		schemaVersion: 1,
+		validate: isWorktreeLockRecord
+	});
 };
 const upsertWorktreeLock = async ({ repoRoot, branch, reason, owner }) => {
 	const { path, record } = await readWorktreeLock({
@@ -833,16 +1593,40 @@ const deleteWorktreeLock = async ({ repoRoot, branch }) => {
 
 //#endregion
 //#region src/integrations/gh.ts
+var GhUnavailableError = class extends Error {
+	code = "GH_UNAVAILABLE";
+	constructor(message = "gh command is unavailable") {
+		super(message);
+		this.name = "GhUnavailableError";
+	}
+};
+var GhCommandError = class extends Error {
+	code = "GH_COMMAND_FAILED";
+	details;
+	constructor({ exitCode, stderr }) {
+		super(`gh command failed with exitCode=${String(exitCode)}`);
+		this.name = "GhCommandError";
+		this.details = {
+			exitCode,
+			stderr
+		};
+	}
+};
 const defaultRunGh = async ({ cwd, args }) => {
-	const result = await execa("gh", [...args], {
-		cwd,
-		reject: false
-	});
-	return {
-		exitCode: result.exitCode ?? 0,
-		stdout: result.stdout,
-		stderr: result.stderr
-	};
+	try {
+		const result = await execa("gh", [...args], {
+			cwd,
+			reject: false
+		});
+		return {
+			exitCode: result.exitCode ?? 0,
+			stdout: result.stdout,
+			stderr: result.stderr
+		};
+	} catch (error) {
+		if (error.code === "ENOENT") throw new GhUnavailableError("gh command not found");
+		throw error;
+	}
 };
 const toTargetBranches = ({ branches, baseBranch }) => {
 	const uniqueBranches = /* @__PURE__ */ new Set();
@@ -944,7 +1728,10 @@ const resolvePrStateByBranchBatch = async ({ repoRoot, baseBranch, branches, ena
 				"headRefName,state,mergedAt,updatedAt,url"
 			]
 		});
-		if (result.exitCode !== 0) return buildUnknownPrStateMap(targetBranches);
+		if (result.exitCode !== 0) throw new GhCommandError({
+			exitCode: result.exitCode,
+			stderr: result.stderr
+		});
 		const prStatusByBranch = parsePrStateByBranch({
 			raw: result.stdout,
 			targetBranches
@@ -952,6 +1739,7 @@ const resolvePrStateByBranchBatch = async ({ repoRoot, baseBranch, branches, ena
 		if (prStatusByBranch === null) return buildUnknownPrStateMap(targetBranches);
 		return prStatusByBranch;
 	} catch (error) {
+		if (error instanceof GhUnavailableError || error instanceof GhCommandError) return buildUnknownPrStateMap(targetBranches);
 		if (error.code === "ENOENT") return buildUnknownPrStateMap(targetBranches);
 		return buildUnknownPrStateMap(targetBranches);
 	}
@@ -1018,35 +1806,8 @@ const listGitWorktrees = async (repoRoot) => {
 
 //#endregion
 //#region src/core/worktree-state.ts
-const resolveBaseBranch$1 = async (repoRoot) => {
-	const explicit = await runGitCommand({
-		cwd: repoRoot,
-		args: [
-			"config",
-			"--get",
-			"vde-worktree.baseBranch"
-		],
-		reject: false
-	});
-	if (explicit.exitCode === 0 && explicit.stdout.trim().length > 0) return explicit.stdout.trim();
-	for (const candidate of ["main", "master"]) if (await doesGitRefExist(repoRoot, `refs/heads/${candidate}`)) return candidate;
-	return null;
-};
-const resolveEnableGh = async (repoRoot) => {
-	const result = await runGitCommand({
-		cwd: repoRoot,
-		args: [
-			"config",
-			"--bool",
-			"--get",
-			"vde-worktree.enableGh"
-		],
-		reject: false
-	});
-	if (result.exitCode !== 0) return true;
-	const value = result.stdout.trim().toLowerCase();
-	if (value === "false" || value === "no" || value === "off" || value === "0") return false;
-	return true;
+const isLockPayload = (parsed) => {
+	return typeof parsed.branch === "string" && typeof parsed.worktreeId === "string" && typeof parsed.reason === "string" && parsed.reason.length > 0 && (typeof parsed.owner === "undefined" || typeof parsed.owner === "string");
 };
 const resolveDirty = async (worktreePath) => {
 	return (await runGitCommand({
@@ -1055,16 +1816,6 @@ const resolveDirty = async (worktreePath) => {
 		reject: false
 	})).stdout.trim().length > 0;
 };
-const parseLockPayload = (content) => {
-	try {
-		const parsed = JSON.parse(content);
-		if (parsed.schemaVersion !== 1) return null;
-		if (typeof parsed.branch !== "string" || typeof parsed.worktreeId !== "string" || typeof parsed.reason !== "string" || parsed.reason.length === 0) return null;
-		return parsed;
-	} catch {
-		return null;
-	}
-};
 const resolveLockState = async ({ repoRoot, branch }) => {
 	if (branch === null) return {
 		value: false,
@@ -1072,38 +1823,62 @@ const resolveLockState = async ({ repoRoot, branch }) => {
 		owner: null
 	};
 	const id = branchToWorktreeId(branch);
-	const lockPath = join(getLocksDirectoryPath(repoRoot), `${id}.json`);
-	try {
-		await access(lockPath, constants.F_OK);
-	} catch {
-		return {
-			value: false,
-			reason: null,
-			owner: null
-		};
-	}
-	try {
-		const lock = parseLockPayload(await readFile(lockPath, "utf8"));
-		if (lock === null) return {
-			value: true,
-			reason: "invalid lock metadata",
-			owner: null
-		};
-		return {
-			value: true,
-			reason: lock.reason,
-			owner: typeof lock.owner === "string" && lock.owner.length > 0 ? lock.owner : null
-		};
-	} catch {
-		return {
-			value: true,
-			reason: "invalid lock metadata",
-			owner: null
-		};
-	}
+	const lock = await readJsonRecord({
+		path: join(getLocksDirectoryPath(repoRoot), `${id}.json`),
+		schemaVersion: 1,
+		validate: isLockPayload
+	});
+	if (lock.exists !== true) return {
+		value: false,
+		reason: null,
+		owner: null
+	};
+	if (lock.valid !== true || lock.record === null) return {
+		value: true,
+		reason: "invalid lock metadata",
+		owner: null
+	};
+	return {
+		value: true,
+		reason: lock.record.reason,
+		owner: typeof lock.record.owner === "string" && lock.record.owner.length > 0 ? lock.record.owner : null
+	};
 };
 const WORK_REFLOG_MESSAGE_PATTERN = /^(commit(?: \([^)]*\))?|cherry-pick|revert|rebase \(pick\)|merge):/;
-const resolveLifecycleFromReflog = async ({ repoRoot, branch, baseBranch }) => {
+const resolveAncestryFromExitCode = (exitCode) => {
+	if (exitCode === 0) return true;
+	if (exitCode === 1) return false;
+	return null;
+};
+const resolveMergedByPr = ({ branch, baseBranch, prStateByBranch }) => {
+	const prStatus = branch === baseBranch ? null : prStateByBranch.get(branch)?.status ?? null;
+	if (prStatus === "merged") return true;
+	if (prStatus === "none" || prStatus === "open" || prStatus === "closed_unmerged") return false;
+	return null;
+};
+const hasLifecycleDivergedHead = (lifecycle) => {
+	return lifecycle.everDiverged === true && lifecycle.lastDivergedHead !== null;
+};
+const parseWorkReflogHeads = (reflogOutput) => {
+	const heads = [];
+	let latestHead = null;
+	for (const line of reflogOutput.split("\n")) {
+		const trimmed = line.trim();
+		if (trimmed.length === 0) continue;
+		const separatorIndex = trimmed.indexOf("	");
+		if (separatorIndex <= 0) continue;
+		const head = trimmed.slice(0, separatorIndex).trim();
+		const message = trimmed.slice(separatorIndex + 1).trim();
+		if (head.length === 0 || WORK_REFLOG_MESSAGE_PATTERN.test(message) !== true) continue;
+		if (latestHead === null) latestHead = head;
+		heads.push(head);
+	}
+	return {
+		heads,
+		latestHead
+	};
+};
+const probeLifecycleFromReflog = async ({ repoRoot, branch, baseBranch }) => {
 	const reflog = await runGitCommand({
 		cwd: repoRoot,
 		args: [
@@ -1118,17 +1893,13 @@ const resolveLifecycleFromReflog = async ({ repoRoot, branch, baseBranch }) => {
 		merged: null,
 		divergedHead: null
 	};
-	let latestWorkHead = null;
-	for (const line of reflog.stdout.split("\n")) {
-		const trimmed = line.trim();
-		if (trimmed.length === 0) continue;
-		const separatorIndex = trimmed.indexOf("	");
-		if (separatorIndex <= 0) continue;
-		const head = trimmed.slice(0, separatorIndex).trim();
-		const message = trimmed.slice(separatorIndex + 1).trim();
-		if (head.length === 0 || WORK_REFLOG_MESSAGE_PATTERN.test(message) !== true) continue;
-		if (latestWorkHead === null) latestWorkHead = head;
-		const result = await runGitCommand({
+	const parsedHeads = parseWorkReflogHeads(reflog.stdout);
+	if (parsedHeads.heads.length === 0) return {
+		merged: null,
+		divergedHead: null
+	};
+	for (const head of parsedHeads.heads) {
+		const merged = resolveAncestryFromExitCode((await runGitCommand({
 			cwd: repoRoot,
 			args: [
 				"merge-base",
@@ -1137,19 +1908,52 @@ const resolveLifecycleFromReflog = async ({ repoRoot, branch, baseBranch }) => {
 				baseBranch
 			],
 			reject: false
-		});
-		if (result.exitCode === 0) return {
+		})).exitCode);
+		if (merged === true) return {
 			merged: true,
 			divergedHead: head
 		};
-		if (result.exitCode !== 1) return {
+		if (merged === null) return {
 			merged: null,
-			divergedHead: latestWorkHead
+			divergedHead: parsedHeads.latestHead
 		};
 	}
 	return {
 		merged: false,
-		divergedHead: latestWorkHead
+		divergedHead: parsedHeads.latestHead
+	};
+};
+const createMergeLifecycleRepository = ({ repoRoot }) => {
+	return { upsert: async ({ branch, baseBranch, observedDivergedHead }) => {
+		return upsertWorktreeMergeLifecycle({
+			repoRoot,
+			branch,
+			baseBranch,
+			observedDivergedHead
+		});
+	} };
+};
+const createMergeProbeRepository = ({ repoRoot }) => {
+	return {
+		probeAncestry: async ({ branch, baseBranch }) => {
+			return resolveAncestryFromExitCode((await runGitCommand({
+				cwd: repoRoot,
+				args: [
+					"merge-base",
+					"--is-ancestor",
+					branch,
+					baseBranch
+				],
+				reject: false
+			})).exitCode);
+		},
+		probeLifecycleFromReflog: async ({ branch, baseBranch }) => {
+			return probeLifecycleFromReflog({
+				repoRoot,
+				branch,
+				baseBranch
+			});
+		}
 	};
 };
 const resolveMergedState = async ({ repoRoot, branch, head, baseBranch, prStateByBranch }) => {
@@ -1158,64 +1962,42 @@ const resolveMergedState = async ({ repoRoot, branch, head, baseBranch, prStateB
 		byPR: null,
 		overall: null
 	};
-	let byAncestry = null;
-	if (baseBranch !== null) {
-		const result = await runGitCommand({
-			cwd: repoRoot,
-			args: [
-				"merge-base",
-				"--is-ancestor",
-				branch,
-				baseBranch
-			],
-			reject: false
-		});
-		if (result.exitCode === 0) byAncestry = true;
-		else if (result.exitCode === 1) byAncestry = false;
-	}
-	const prStatus = branch === baseBranch ? null : prStateByBranch.get(branch)?.status ?? null;
-	let byPR = null;
-	if (prStatus === "merged") byPR = true;
-	else if (prStatus === "none" || prStatus === "open" || prStatus === "closed_unmerged") byPR = false;
+	const mergeProbeRepository = createMergeProbeRepository({ repoRoot });
+	const mergeLifecycleRepository = createMergeLifecycleRepository({ repoRoot });
+	const byAncestry = baseBranch === null ? null : await mergeProbeRepository.probeAncestry({
+		branch,
+		baseBranch
+	});
+	const byPR = resolveMergedByPr({
+		branch,
+		baseBranch,
+		prStateByBranch
+	});
 	let byLifecycle = null;
 	if (baseBranch !== null) {
-		const lifecycle = await upsertWorktreeMergeLifecycle({
-			repoRoot,
+		const lifecycle = await mergeLifecycleRepository.upsert({
 			branch,
 			baseBranch,
 			observedDivergedHead: byAncestry === false ? head : null
 		});
 		if (byAncestry === false) byLifecycle = false;
-		else if (byAncestry === true) if (lifecycle.everDiverged !== true || lifecycle.lastDivergedHead === null) if (byPR === true) byLifecycle = null;
+		else if (byAncestry === true) if (hasLifecycleDivergedHead(lifecycle)) byLifecycle = await mergeProbeRepository.probeAncestry({
+			branch: lifecycle.lastDivergedHead,
+			baseBranch
+		});
+		else if (byPR === true) byLifecycle = null;
 		else {
-			const probe = await resolveLifecycleFromReflog({
-				repoRoot,
+			const probe = await mergeProbeRepository.probeLifecycleFromReflog({
 				branch,
 				baseBranch
 			});
 			byLifecycle = probe.merged;
-			if (probe.divergedHead !== null) await upsertWorktreeMergeLifecycle({
-				repoRoot,
+			if (probe.divergedHead !== null) await mergeLifecycleRepository.upsert({
 				branch,
 				baseBranch,
 				observedDivergedHead: probe.divergedHead
 			});
 		}
-		else {
-			const lifecycleResult = await runGitCommand({
-				cwd: repoRoot,
-				args: [
-					"merge-base",
-					"--is-ancestor",
-					lifecycle.lastDivergedHead,
-					baseBranch
-				],
-				reject: false
-			});
-			if (lifecycleResult.exitCode === 0) byLifecycle = true;
-			else if (lifecycleResult.exitCode === 1) byLifecycle = false;
-			else byLifecycle = null;
-		}
 	}
 	return {
 		byAncestry,
@@ -1316,17 +2098,13 @@ const enrichWorktree = async ({ repoRoot, worktree, baseBranch, prStateByBranch
 		upstream
 	};
 };
-const collectWorktreeSnapshot = async (repoRoot, { noGh = false } = {}) => {
-	const [baseBranch, worktrees, enableGh] = await Promise.all([
-		resolveBaseBranch$1(repoRoot),
-		listGitWorktrees(repoRoot),
-		resolveEnableGh(repoRoot)
-	]);
+const collectWorktreeSnapshot = async (repoRoot, { baseBranch = null, ghEnabled = true, noGh = false } = {}) => {
+	const worktrees = await listGitWorktrees(repoRoot);
 	const prStateByBranch = await resolvePrStateByBranchBatch({
 		repoRoot,
 		baseBranch,
 		branches: worktrees.map((worktree) => worktree.branch),
-		enabled: enableGh && noGh !== true
+		enabled: ghEnabled && noGh !== true
 	});
 	return {
 		repoRoot,
@@ -1350,10 +2128,55 @@ const RESERVED_FZF_ARGS = new Set([
 	"prompt",
 	"layout",
 	"height",
-	"border"
+	"border",
+	"tmux"
 ]);
 const ANSI_ESCAPE_SEQUENCE_PATTERN = String.raw`\u001B\[[0-?]*[ -/]*[@-~]`;
 const ANSI_ESCAPE_SEQUENCE_REGEX = new RegExp(ANSI_ESCAPE_SEQUENCE_PATTERN, "g");
+var FzfError = class extends Error {
+	code;
+	constructor(options) {
+		super(options.message);
+		this.name = "FzfError";
+		this.code = options.code;
+	}
+};
+var FzfDependencyError = class extends FzfError {
+	constructor(message = "fzf is required for interactive selection") {
+		super({
+			code: "FZF_DEPENDENCY_MISSING",
+			message
+		});
+		this.name = "FzfDependencyError";
+	}
+};
+var FzfInteractiveRequiredError = class extends FzfError {
+	constructor(message = "fzf selection requires an interactive terminal") {
+		super({
+			code: "FZF_INTERACTIVE_REQUIRED",
+			message
+		});
+		this.name = "FzfInteractiveRequiredError";
+	}
+};
+var FzfInvalidArgumentError = class extends FzfError {
+	constructor(message) {
+		super({
+			code: "FZF_INVALID_ARGUMENT",
+			message
+		});
+		this.name = "FzfInvalidArgumentError";
+	}
+};
+var FzfInvalidSelectionError = class extends FzfError {
+	constructor(message) {
+		super({
+			code: "FZF_INVALID_SELECTION",
+			message
+		});
+		this.name = "FzfInvalidSelectionError";
+	}
+};
 const sanitizeCandidate = (value) => value.replace(/[\r\n]+/g, " ").trim();
 const stripAnsi = (value) => value.replace(ANSI_ESCAPE_SEQUENCE_REGEX, "");
 const stripTrailingNewlines = (value) => value.replace(/[\r\n]+$/g, "");
@@ -1362,12 +2185,12 @@ const buildFzfInput = (candidates) => {
 };
 const validateExtraFzfArgs = (fzfExtraArgs) => {
 	for (const arg of fzfExtraArgs) {
-		if (typeof arg !== "string" || arg.length === 0) throw new Error("Empty value is not allowed for --fzf-arg");
+		if (typeof arg !== "string" || arg.length === 0) throw new FzfInvalidArgumentError("Empty value is not allowed for --fzf-arg");
 		if (!arg.startsWith("--")) continue;
 		const withoutPrefix = arg.slice(2);
 		if (withoutPrefix.length === 0) continue;
 		const optionName = withoutPrefix.split("=")[0];
-		if (optionName !== void 0 && RESERVED_FZF_ARGS.has(optionName)) throw new Error(`--fzf-arg cannot override reserved fzf option: --${optionName}`);
+		if (optionName !== void 0 && RESERVED_FZF_ARGS.has(optionName)) throw new FzfInvalidArgumentError(`--fzf-arg cannot override reserved fzf option: --${optionName}`);
 	}
 };
 const buildFzfArgs = ({ prompt, fzfExtraArgs }) => {
@@ -1390,6 +2213,13 @@ const defaultCheckFzfAvailability = async () => {
 		throw error;
 	}
 };
+const defaultCheckFzfTmuxSupport = async () => {
+	try {
+		return (await execa(FZF_BINARY, ["--help"], { timeout: FZF_CHECK_TIMEOUT_MS })).stdout.includes("--tmux");
+	} catch {
+		return false;
+	}
+};
 const defaultRunFzf = async ({ args, input, cwd, env }) => {
 	return { stdout: (await execa(FZF_BINARY, args, {
 		input,
@@ -1400,33 +2230,68 @@ const defaultRunFzf = async ({ args, input, cwd, env }) => {
 };
 const ensureFzfAvailable = async (checkFzfAvailability) => {
 	if (await checkFzfAvailability()) return;
-	throw new Error("fzf is required for interactive selection");
+	throw new FzfDependencyError();
+};
+const shouldTryTmuxPopup = async ({ surface, env, checkFzfTmuxSupport }) => {
+	if (surface === "inline") return false;
+	if (surface === "tmux-popup") return true;
+	if (typeof env.TMUX !== "string" || env.TMUX.length === 0) return false;
+	try {
+		return await checkFzfTmuxSupport();
+	} catch {
+		return false;
+	}
 };
-const selectPathWithFzf = async ({ candidates, prompt = "worktree> ", fzfExtraArgs = [], cwd = process.cwd(), env = process.env, isInteractive = () => process.stdout.isTTY === true && process.stderr.isTTY === true, checkFzfAvailability = defaultCheckFzfAvailability, runFzf = defaultRunFzf }) => {
-	if (candidates.length === 0) throw new Error("No candidates provided for fzf selection");
-	if (isInteractive() !== true) throw new Error("fzf selection requires an interactive terminal");
+const isTmuxUnknownOptionError = (error) => {
+	const execaError = error;
+	const text = [
+		execaError.message,
+		execaError.shortMessage,
+		execaError.stderr,
+		execaError.stdout
+	].filter((value) => typeof value === "string" && value.length > 0).join("\n");
+	return /unknown option.*--tmux|--tmux.*unknown option/i.test(text);
+};
+const selectPathWithFzf = async ({ candidates, prompt = "worktree> ", surface = "inline", tmuxPopupOpts = "80%,70%", fzfExtraArgs = [], cwd = process.cwd(), env = process.env, isInteractive = () => process.stdout.isTTY === true && process.stderr.isTTY === true, checkFzfAvailability = defaultCheckFzfAvailability, checkFzfTmuxSupport = defaultCheckFzfTmuxSupport, runFzf = defaultRunFzf }) => {
+	if (candidates.length === 0) throw new FzfInvalidArgumentError("No candidates provided for fzf selection");
+	if (isInteractive() !== true) throw new FzfInteractiveRequiredError();
 	await ensureFzfAvailable(checkFzfAvailability);
-	const args = buildFzfArgs({
+	const baseArgs = buildFzfArgs({
 		prompt,
 		fzfExtraArgs
 	});
+	const tryTmuxPopup = await shouldTryTmuxPopup({
+		surface,
+		env,
+		checkFzfTmuxSupport
+	});
+	const args = tryTmuxPopup ? [...baseArgs, `--tmux=${tmuxPopupOpts}`] : baseArgs;
 	const input = buildFzfInput(candidates);
-	if (input.length === 0) throw new Error("All candidates are empty after sanitization");
+	if (input.length === 0) throw new FzfInvalidArgumentError("All candidates are empty after sanitization");
 	const candidateSet = new Set(input.split("\n").map((candidate) => stripAnsi(candidate)));
-	try {
+	const runWithValidation = async (fzfArgs) => {
 		const selectedPath = stripAnsi(stripTrailingNewlines((await runFzf({
-			args,
+			args: fzfArgs,
 			input,
 			cwd,
 			env
 		})).stdout));
 		if (selectedPath.length === 0) return { status: "cancelled" };
-		if (!candidateSet.has(selectedPath)) throw new Error("fzf returned a value that is not in the candidate list");
+		if (!candidateSet.has(selectedPath)) throw new FzfInvalidSelectionError("fzf returned a value that is not in the candidate list");
 		return {
 			status: "selected",
 			path: selectedPath
 		};
+	};
+	try {
+		return await runWithValidation(args);
 	} catch (error) {
+		if (tryTmuxPopup && isTmuxUnknownOptionError(error)) try {
+			return await runWithValidation(baseArgs);
+		} catch (fallbackError) {
+			if (fallbackError.exitCode === 130) return { status: "cancelled" };
+			throw fallbackError;
+		}
 		if (error.exitCode === 130) return { status: "cancelled" };
 		throw error;
 	}
@@ -1483,6 +2348,157 @@ const createLogger = (options = {}) => {
 	return build(prefix, level);
 };
 
+//#endregion
+//#region src/cli/commands/handler-groups.ts
+const createHandlerMap = (entries) => {
+	return new Map(entries);
+};
+const dispatchCommandHandler = async ({ command, handlers }) => {
+	const handler = handlers.get(command);
+	if (handler === void 0) return;
+	return await handler();
+};
+const createEarlyRepoCommandHandlers = ({ initHandler, listHandler, statusHandler, pathHandler }) => {
+	return createHandlerMap([
+		["init", initHandler],
+		["list", listHandler],
+		["status", statusHandler],
+		["path", pathHandler]
+	]);
+};
+const createWriteCommandHandlers = ({ newHandler, switchHandler }) => {
+	return createHandlerMap([["new", newHandler], ["switch", switchHandler]]);
+};
+const createWriteMutationHandlers = ({ mvHandler, delHandler }) => {
+	return createHandlerMap([["mv", mvHandler], ["del", delHandler]]);
+};
+const createWorktreeActionHandlers = ({ goneHandler, getHandler, extractHandler }) => {
+	return createHandlerMap([
+		["gone", goneHandler],
+		["get", getHandler],
+		["extract", extractHandler]
+	]);
+};
+const createSynchronizationHandlers = ({ absorbHandler, unabsorbHandler, useHandler }) => {
+	return createHandlerMap([
+		["absorb", absorbHandler],
+		["unabsorb", unabsorbHandler],
+		["use", useHandler]
+	]);
+};
+const createMiscCommandHandlers = ({ execHandler, invokeHandler, copyHandler, linkHandler, lockHandler, unlockHandler, cdHandler }) => {
+	return createHandlerMap([
+		["exec", execHandler],
+		["invoke", invokeHandler],
+		["copy", copyHandler],
+		["link", linkHandler],
+		["lock", lockHandler],
+		["unlock", unlockHandler],
+		["cd", cdHandler]
+	]);
+};
+
+//#endregion
+//#region src/cli/commands/read/dispatcher.ts
+const handled = (exitCode) => {
+	return {
+		handled: true,
+		exitCode
+	};
+};
+const NOT_HANDLED = { handled: false };
+const dispatchReadOnlyCommands = async (input) => {
+	if (input.parsedArgs.help === true) {
+		const commandHelpTarget = input.command !== "unknown" && input.command !== "help" ? input.command : null;
+		if (commandHelpTarget !== null) {
+			const entry = input.findCommandHelp(commandHelpTarget);
+			if (entry !== void 0) {
+				input.stdout(`${input.renderCommandHelpText({ entry })}\n`);
+				return handled(EXIT_CODE.OK);
+			}
+		}
+		input.stdout(`${input.renderGeneralHelpText({ version: input.version })}\n`);
+		return handled(EXIT_CODE.OK);
+	}
+	if (input.parsedArgs.version === true) {
+		input.stdout(input.version);
+		return handled(EXIT_CODE.OK);
+	}
+	if (input.positionals.length === 0) {
+		input.stdout(`${input.renderGeneralHelpText({ version: input.version })}\n`);
+		return handled(EXIT_CODE.OK);
+	}
+	if (input.command === "help") {
+		const helpTarget = input.positionals[1];
+		if (typeof helpTarget !== "string" || helpTarget.length === 0) {
+			input.stdout(`${input.renderGeneralHelpText({ version: input.version })}\n`);
+			return handled(EXIT_CODE.OK);
+		}
+		const entry = input.findCommandHelp(helpTarget);
+		if (entry === void 0) throw createCliError("INVALID_ARGUMENT", {
+			message: `Unknown command for help: ${helpTarget}`,
+			details: {
+				requested: helpTarget,
+				availableCommands: input.availableCommandNames
+			}
+		});
+		input.stdout(`${input.renderCommandHelpText({ entry })}\n`);
+		return handled(EXIT_CODE.OK);
+	}
+	if (input.command === "completion") {
+		input.ensureArgumentCount({
+			command: input.command,
+			args: input.commandArgs,
+			min: 1,
+			max: 1
+		});
+		const shell = input.resolveCompletionShell(input.commandArgs[0]);
+		const script = await input.loadCompletionScript(shell);
+		if (input.parsedArgs.install === true) {
+			const destinationPath = input.resolveCompletionInstallPath({
+				shell,
+				requestedPath: input.readStringOption(input.parsedArgs, "path")
+			});
+			await input.installCompletionScript({
+				content: script,
+				destinationPath
+			});
+			if (input.jsonEnabled) {
+				input.stdout(JSON.stringify(input.buildJsonSuccess({
+					command: input.command,
+					status: "ok",
+					repoRoot: null,
+					details: {
+						shell,
+						installed: true,
+						path: destinationPath
+					}
+				})));
+				return handled(EXIT_CODE.OK);
+			}
+			input.stdout(`installed completion: ${destinationPath}`);
+			if (shell === "zsh") input.stdout("zsh note: ensure completion path is in fpath, then run: autoload -Uz compinit && compinit");
+			return handled(EXIT_CODE.OK);
+		}
+		if (input.jsonEnabled) {
+			input.stdout(JSON.stringify(input.buildJsonSuccess({
+				command: input.command,
+				status: "ok",
+				repoRoot: null,
+				details: {
+					shell,
+					installed: false,
+					script
+				}
+			})));
+			return handled(EXIT_CODE.OK);
+		}
+		input.stdout(script);
+		return handled(EXIT_CODE.OK);
+	}
+	return NOT_HANDLED;
+};
+
 //#endregion
 //#region src/cli/package-version.ts
 const CANDIDATE_PATHS = ["../package.json", "../../package.json"];
@@ -1514,9 +2530,7 @@ const CD_FZF_EXTRA_ARGS = [
 	"--preview-window=right,60%,wrap",
 	"--ansi"
 ];
-const LIST_TABLE_COLUMN_COUNT = 8;
-const LIST_TABLE_PATH_COLUMN_INDEX = 7;
-const LIST_TABLE_PATH_MIN_WIDTH = 12;
+const DEFAULT_LIST_TABLE_COLUMNS = [...LIST_TABLE_COLUMNS];
 const LIST_TABLE_CELL_HORIZONTAL_PADDING = 2;
 const COMPLETION_SHELLS = ["zsh", "fish"];
 const COMPLETION_FILE_BY_SHELL = {
@@ -1538,6 +2552,10 @@ const CATPPUCCIN_MOCHA = {
 	overlay0: "#6c7086"
 };
 const identityColor = (value) => value;
+const hasDefaultListColumnOrder = (columns) => {
+	if (columns.length !== DEFAULT_LIST_TABLE_COLUMNS.length) return false;
+	return columns.every((column, index) => column === DEFAULT_LIST_TABLE_COLUMNS[index]);
+};
 const createCatppuccinTheme = ({ enabled }) => {
 	if (enabled !== true) return {
 		header: identityColor,
@@ -1848,6 +2866,7 @@ const commandHelpEntries = [
 		options: ["--install", "--path <file>"]
 	}
 ];
+const commandHelpNames = commandHelpEntries.map((entry) => entry.name);
 const splitRawArgsByDoubleDash = (args) => {
 	const separatorIndex = args.indexOf("--");
 	if (separatorIndex < 0) return {
@@ -1865,7 +2884,8 @@ const toKebabCase = (value) => {
 const toOptionSpec = (kind, optionName) => {
 	return {
 		kind,
-		allowOptionLikeValue: optionNamesAllowOptionLikeValue.has(optionName)
+		allowOptionLikeValue: optionNamesAllowOptionLikeValue.has(optionName),
+		allowNegation: kind === "boolean"
 	};
 };
 const buildOptionSpecs = (argsDef) => {
@@ -1893,6 +2913,69 @@ const buildOptionSpecs = (argsDef) => {
 		shortOptions
 	};
 };
+const ensureOptionValueToken = ({ valueToken, optionLabel, optionSpec }) => {
+	if (valueToken.length === 0) throw createCliError("INVALID_ARGUMENT", { message: `Missing value for option: ${optionLabel}` });
+	if (valueToken.startsWith("-") && optionSpec.allowOptionLikeValue !== true) throw createCliError("INVALID_ARGUMENT", { message: `Missing value for option: ${optionLabel}` });
+};
+const resolveLongOption = ({ rawOptionName, optionSpecs }) => {
+	const directOptionSpec = optionSpecs.longOptions.get(rawOptionName);
+	if (directOptionSpec !== void 0) return {
+		optionSpec: directOptionSpec,
+		optionName: rawOptionName
+	};
+	if (rawOptionName.startsWith("no-")) {
+		const optionName = rawOptionName.slice(3);
+		const negatedOptionSpec = optionSpecs.longOptions.get(optionName);
+		if (negatedOptionSpec?.allowNegation === true) return {
+			optionSpec: negatedOptionSpec,
+			optionName
+		};
+	}
+};
+const validateLongOptionToken = ({ args, index, token, optionSpecs }) => {
+	const value = token.slice(2);
+	if (value.length === 0) return index;
+	const separatorIndex = value.indexOf("=");
+	const rawOptionName = separatorIndex >= 0 ? value.slice(0, separatorIndex) : value;
+	const resolved = resolveLongOption({
+		rawOptionName,
+		optionSpecs
+	});
+	if (resolved === void 0) throw createCliError("INVALID_ARGUMENT", { message: `Unknown option: --${rawOptionName}` });
+	if (resolved.optionSpec.kind !== "value") return index;
+	if (separatorIndex >= 0) {
+		if (value.slice(separatorIndex + 1).length === 0) throw createCliError("INVALID_ARGUMENT", { message: `Missing value for option: --${rawOptionName}` });
+		return index;
+	}
+	const nextToken = args[index + 1];
+	if (typeof nextToken !== "string") throw createCliError("INVALID_ARGUMENT", { message: `Missing value for option: --${rawOptionName}` });
+	ensureOptionValueToken({
+		valueToken: nextToken,
+		optionLabel: `--${rawOptionName}`,
+		optionSpec: resolved.optionSpec
+	});
+	return index + 1;
+};
+const validateShortOptionToken = ({ args, index, token, optionSpecs }) => {
+	const shortFlags = token.slice(1);
+	for (let flagIndex = 0; flagIndex < shortFlags.length; flagIndex += 1) {
+		const option = shortFlags[flagIndex];
+		if (typeof option !== "string" || option.length === 0) continue;
+		const optionSpec = optionSpecs.shortOptions.get(option);
+		if (optionSpec === void 0) throw createCliError("INVALID_ARGUMENT", { message: `Unknown option: -${option}` });
+		if (optionSpec.kind !== "value") continue;
+		if (flagIndex < shortFlags.length - 1) throw createCliError("INVALID_ARGUMENT", { message: `Missing value for option: -${option}` });
+		const nextToken = args[index + 1];
+		if (typeof nextToken !== "string") throw createCliError("INVALID_ARGUMENT", { message: `Missing value for option: -${option}` });
+		ensureOptionValueToken({
+			valueToken: nextToken,
+			optionLabel: `-${option}`,
+			optionSpec
+		});
+		return index + 1;
+	}
+	return index;
+};
 const validateRawOptions = (args, optionSpecs) => {
 	for (let index = 0; index < args.length; index += 1) {
 		const token = args[index];
@@ -1900,39 +2983,20 @@ const validateRawOptions = (args, optionSpecs) => {
 		if (token === "--") break;
 		if (!token.startsWith("-") || token === "-") continue;
 		if (token.startsWith("--")) {
-			const value = token.slice(2);
-			if (value.length === 0) continue;
-			const separatorIndex = value.indexOf("=");
-			const rawOptionName = separatorIndex >= 0 ? value.slice(0, separatorIndex) : value;
-			const directOptionSpec = optionSpecs.longOptions.get(rawOptionName);
-			const optionNameForNegation = rawOptionName.startsWith("no-") ? rawOptionName.slice(3) : rawOptionName;
-			const optionSpec = directOptionSpec ?? optionSpecs.longOptions.get(optionNameForNegation);
-			if (optionSpec === void 0) throw createCliError("INVALID_ARGUMENT", { message: `Unknown option: --${rawOptionName}` });
-			if (optionSpec.kind === "value") if (separatorIndex >= 0) {
-				if (value.slice(separatorIndex + 1).length === 0) throw createCliError("INVALID_ARGUMENT", { message: `Missing value for option: --${rawOptionName}` });
-			} else {
-				const nextToken = args[index + 1];
-				if (typeof nextToken !== "string" || nextToken.length === 0) throw createCliError("INVALID_ARGUMENT", { message: `Missing value for option: --${rawOptionName}` });
-				if (nextToken.startsWith("-") && optionSpec.allowOptionLikeValue !== true) throw createCliError("INVALID_ARGUMENT", { message: `Missing value for option: --${rawOptionName}` });
-				index += 1;
-			}
+			index = validateLongOptionToken({
+				args,
+				index,
+				token,
+				optionSpecs
+			});
 			continue;
 		}
-		const shortFlags = token.slice(1);
-		for (let flagIndex = 0; flagIndex < shortFlags.length; flagIndex += 1) {
-			const option = shortFlags[flagIndex];
-			if (typeof option !== "string" || option.length === 0) continue;
-			const optionSpec = optionSpecs.shortOptions.get(option);
-			if (optionSpec === void 0) throw createCliError("INVALID_ARGUMENT", { message: `Unknown option: -${option}` });
-			if (optionSpec.kind === "value") {
-				if (flagIndex < shortFlags.length - 1) break;
-				const nextToken = args[index + 1];
-				if (typeof nextToken !== "string" || nextToken.length === 0) throw createCliError("INVALID_ARGUMENT", { message: `Missing value for option: -${option}` });
-				if (nextToken.startsWith("-") && optionSpec.allowOptionLikeValue !== true) throw createCliError("INVALID_ARGUMENT", { message: `Missing value for option: -${option}` });
-				index += 1;
-				break;
-			}
-		}
+		index = validateShortOptionToken({
+			args,
+			index,
+			token,
+			optionSpecs
+		});
 	}
 };
 const getPositionals = (args) => {
@@ -1985,85 +3049,29 @@ const ensureArgumentCount = ({ command, args, min, max }) => {
 const ensureHasCommandAfterDoubleDash = ({ command, argsAfterDoubleDash }) => {
 	if (argsAfterDoubleDash.length === 0) throw createCliError("INVALID_ARGUMENT", { message: `${command} requires arguments after --` });
 };
-const readGitConfigInt = async (repoRoot, key) => {
-	const result = await runGitCommand({
-		cwd: repoRoot,
-		args: [
-			"config",
-			"--get",
-			key
-		],
-		reject: false
-	});
-	if (result.exitCode !== 0) return;
-	const parsed = Number.parseInt(result.stdout.trim(), 10);
-	return Number.isFinite(parsed) && parsed > 0 ? parsed : void 0;
-};
-const readGitConfigBoolean = async (repoRoot, key) => {
-	const result = await runGitCommand({
-		cwd: repoRoot,
-		args: [
-			"config",
-			"--bool",
-			"--get",
-			key
-		],
-		reject: false
-	});
-	if (result.exitCode !== 0) return;
-	const value = result.stdout.trim().toLowerCase();
-	if (value === "true" || value === "yes" || value === "on" || value === "1") return true;
-	if (value === "false" || value === "no" || value === "off" || value === "0") return false;
-};
-const resolveConfiguredBaseRemote = async (repoRoot) => {
-	const configured = await runGitCommand({
+const resolveBaseBranch = async ({ repoRoot, config }) => {
+	if (typeof config.git.baseBranch === "string" && config.git.baseBranch.length > 0) return config.git.baseBranch;
+	const remote = config.git.baseRemote;
+	const resolved = await runGitCommand({
 		cwd: repoRoot,
 		args: [
-			"config",
-			"--get",
-			"vde-worktree.baseRemote"
-		],
-		reject: false
-	});
-	if (configured.exitCode === 0 && configured.stdout.trim().length > 0) return configured.stdout.trim();
-	return "origin";
-};
-const resolveBaseBranch = async (repoRoot) => {
-	const configured = await runGitCommand({
-		cwd: repoRoot,
-		args: [
-			"config",
-			"--get",
-			"vde-worktree.baseBranch"
+			"symbolic-ref",
+			"--quiet",
+			"--short",
+			`refs/remotes/${remote}/HEAD`
 		],
 		reject: false
 	});
-	if (configured.exitCode === 0 && configured.stdout.trim().length > 0) return configured.stdout.trim();
-	const remotesToProbe = [
-		await resolveConfiguredBaseRemote(repoRoot),
-		"origin",
-		"upstream"
-	].filter((value, index, arr) => {
-		return arr.indexOf(value) === index;
-	});
-	for (const remote of remotesToProbe) {
-		const resolved = await runGitCommand({
-			cwd: repoRoot,
-			args: [
-				"symbolic-ref",
-				"--quiet",
-				"--short",
-				`refs/remotes/${remote}/HEAD`
-			],
-			reject: false
-		});
-		if (resolved.exitCode !== 0) continue;
+	if (resolved.exitCode === 0) {
 		const raw = resolved.stdout.trim();
 		const prefix = `${remote}/`;
 		if (raw.startsWith(prefix)) return raw.slice(prefix.length);
 	}
 	for (const candidate of ["main", "master"]) if (await doesGitRefExist(repoRoot, `refs/heads/${candidate}`)) return candidate;
-	throw createCliError("INVALID_ARGUMENT", { message: "Unable to resolve base branch. Configure vde-worktree.baseBranch." });
+	throw createCliError("INVALID_ARGUMENT", {
+		message: "Unable to resolve base branch from config.yml (baseRemote/HEAD -> main/master).",
+		details: { remote }
+	});
 };
 const ensureTargetPathWritable = async (targetPath) => {
 	try {
@@ -2256,7 +3264,7 @@ const validateDeleteSafety = ({ target, forceFlags }) => {
 const resolveLinkTargetPath = ({ sourcePath, destinationPath }) => {
 	return relative(dirname(destinationPath), sourcePath);
 };
-const resolveFileCopyTargets = ({ repoRoot, worktreePath, relativePath }) => {
+const resolveFileCopyTargets = ({ repoRoot, targetWorktreeRoot, relativePath }) => {
 	const sourcePath = resolveRepoRelativePath({
 		repoRoot,
 		relativePath
@@ -2264,13 +3272,32 @@ const resolveFileCopyTargets = ({ repoRoot, worktreePath, relativePath }) => {
 	const relativeFromRoot = relative(repoRoot, sourcePath);
 	return {
 		sourcePath,
-		destinationPath: ensurePathInsideRepo({
-			repoRoot,
-			path: resolve(worktreePath, relativeFromRoot)
+		destinationPath: ensurePathInsideRoot({
+			rootPath: targetWorktreeRoot,
+			path: resolve(targetWorktreeRoot, relativeFromRoot),
+			message: "Path is outside target worktree root"
 		}),
 		relativeFromRoot
 	};
 };
+const resolveTargetWorktreeRootForCopyLink = ({ repoContext, snapshot }) => {
+	const rawTarget = process.env.WT_WORKTREE_PATH ?? repoContext.currentWorktreeRoot;
+	const resolvedTarget = resolvePathFromCwd({
+		cwd: repoContext.currentWorktreeRoot,
+		path: rawTarget
+	});
+	const matched = snapshot.worktrees.filter((worktree) => {
+		return worktree.path === resolvedTarget || resolvedTarget.startsWith(`${worktree.path}${sep}`);
+	}).sort((a, b) => b.path.length - a.path.length)[0];
+	if (matched === void 0) throw createCliError("WORKTREE_NOT_FOUND", {
+		message: "copy/link target worktree not found",
+		details: {
+			rawTarget,
+			resolvedTarget
+		}
+	});
+	return matched.path;
+};
 const ensureBranchIsNotPrimary = ({ branch, baseBranch }) => {
 	if (branch !== baseBranch) return;
 	throw createCliError("INVALID_ARGUMENT", {
@@ -2281,12 +3308,14 @@ const ensureBranchIsNotPrimary = ({ branch, baseBranch }) => {
 		}
 	});
 };
-const toManagedWorktreeName = ({ repoRoot, worktreePath }) => {
-	const relativePath = relative(getWorktreeRootPath(repoRoot), worktreePath);
-	if (relativePath.length === 0 || relativePath === "." || relativePath === ".." || relativePath.startsWith(`..${sep}`)) return null;
-	return relativePath.split(sep).join("/");
+const toManagedWorktreeName = ({ managedWorktreeRoot, worktreePath }) => {
+	if (isManagedWorktreePath({
+		worktreePath,
+		managedWorktreeRoot
+	}) !== true) return null;
+	return relative(managedWorktreeRoot, worktreePath).split(sep).join("/");
 };
-const resolveManagedWorktreePathFromName = ({ repoRoot, optionName, worktreeName }) => {
+const resolveManagedWorktreePathFromName = ({ managedWorktreeRoot, optionName, worktreeName }) => {
 	const normalized = worktreeName.trim();
 	if (normalized.length === 0) throw createCliError("INVALID_ARGUMENT", {
 		message: `${optionName} requires non-empty worktree name`,
@@ -2295,18 +3324,10 @@ const resolveManagedWorktreePathFromName = ({ repoRoot, optionName, worktreeName
 			worktreeName
 		}
 	});
-	if (normalized === ".worktree" || normalized.startsWith(".worktree/") || normalized.startsWith(".worktree\\")) throw createCliError("INVALID_ARGUMENT", {
-		message: `${optionName} expects vw-managed worktree name (without .worktree/ prefix)`,
-		details: {
-			optionName,
-			worktreeName
-		}
-	});
-	const worktreeRoot = getWorktreeRootPath(repoRoot);
 	let resolvedPath;
 	try {
 		resolvedPath = resolveRepoRelativePath({
-			repoRoot: worktreeRoot,
+			repoRoot: managedWorktreeRoot,
 			relativePath: normalized
 		});
 	} catch (error) {
@@ -2319,7 +3340,7 @@ const resolveManagedWorktreePathFromName = ({ repoRoot, optionName, worktreeName
 			cause: error
 		});
 	}
-	if (resolvedPath === worktreeRoot) throw createCliError("INVALID_ARGUMENT", {
+	if (resolvedPath === managedWorktreeRoot) throw createCliError("INVALID_ARGUMENT", {
 		message: `${optionName} expects vw-managed worktree name`,
 		details: {
 			optionName,
@@ -2328,16 +3349,16 @@ const resolveManagedWorktreePathFromName = ({ repoRoot, optionName, worktreeName
 	});
 	return resolvedPath;
 };
-const resolveManagedNonPrimaryWorktreeByBranch = ({ repoRoot, branch, worktrees, optionName, worktreeName, role }) => {
+const resolveManagedNonPrimaryWorktreeByBranch = ({ repoRoot, managedWorktreeRoot, branch, worktrees, optionName, worktreeName, role }) => {
 	const managedCandidates = worktrees.filter((worktree) => {
 		return worktree.branch === branch && worktree.path !== repoRoot && toManagedWorktreeName({
-			repoRoot,
+			managedWorktreeRoot,
 			worktreePath: worktree.path
 		}) !== null;
 	});
 	if (typeof worktreeName === "string") {
 		const resolvedPath = resolveManagedWorktreePathFromName({
-			repoRoot,
+			managedWorktreeRoot,
 			optionName,
 			worktreeName
 		});
@@ -2368,7 +3389,7 @@ const resolveManagedNonPrimaryWorktreeByBranch = ({ repoRoot, branch, worktrees,
 			optionName,
 			candidates: managedCandidates.map((worktree) => {
 				return toManagedWorktreeName({
-					repoRoot,
+					managedWorktreeRoot,
 					worktreePath: worktree.path
 				}) ?? worktree.path;
 			})
@@ -2525,19 +3546,24 @@ const resolveListColumnContentWidth = ({ rows, columnIndex }) => {
 		return Math.max(width, stringWidth(cell));
 	}, 0);
 };
-const resolveListPathColumnWidth = ({ rows, disablePathTruncation }) => {
-	if (disablePathTruncation) return null;
+const resolveListPathColumnWidth = ({ rows, columns, truncateMode, fullPath, minWidth }) => {
+	const pathColumnIndex = columns.indexOf("path");
+	if (pathColumnIndex < 0) return null;
+	if (fullPath || truncateMode === "never") return null;
 	if (process.stdout.isTTY !== true) return null;
 	const terminalColumns = process.stdout.columns;
 	if (typeof terminalColumns !== "number" || Number.isFinite(terminalColumns) !== true || terminalColumns <= 0) return null;
-	const measuredNonPathWidth = Array.from({ length: LIST_TABLE_PATH_COLUMN_INDEX }).map((_, index) => resolveListColumnContentWidth({
-		rows,
-		columnIndex: index
-	})).reduce((sum, width) => sum + width, 0);
-	const borderWidth = LIST_TABLE_COLUMN_COUNT + 1;
-	const paddingWidth = LIST_TABLE_COLUMN_COUNT * LIST_TABLE_CELL_HORIZONTAL_PADDING;
+	const measuredNonPathWidth = columns.map((_, index) => {
+		if (index === pathColumnIndex) return 0;
+		return resolveListColumnContentWidth({
+			rows,
+			columnIndex: index
+		});
+	}).reduce((sum, width) => sum + width, 0);
+	const borderWidth = columns.length + 1;
+	const paddingWidth = columns.length * LIST_TABLE_CELL_HORIZONTAL_PADDING;
 	const availablePathWidth = Math.floor(terminalColumns) - borderWidth - paddingWidth - measuredNonPathWidth;
-	return Math.max(LIST_TABLE_PATH_MIN_WIDTH, availablePathWidth);
+	return Math.max(minWidth, availablePathWidth);
 };
 const resolveAheadBehindAgainstBaseBranch = async ({ repoRoot, baseBranch, worktree }) => {
 	if (baseBranch === null) return {
@@ -2878,7 +3904,7 @@ const createCli = (options = {}) => {
 		from: {
 			type: "string",
 			valueHint: "value",
-			description: "For extract: filesystem path. For absorb: managed worktree name without .worktree/ prefix."
+			description: "For extract: filesystem path. For absorb: managed worktree name."
 		},
 		to: {
 			type: "string",
@@ -2931,135 +3957,76 @@ const createCli = (options = {}) => {
 			const parsedArgsRecord = parsedArgs;
 			const positionals = getPositionals(parsedArgs);
 			command = positionals[0] ?? "unknown";
+			const commandArgs = positionals.slice(1);
 			jsonEnabled = parsedArgs.json === true;
-			if (parsedArgs.help === true) {
-				const commandHelpTarget = typeof command === "string" && command !== "unknown" && command !== "help" ? command : null;
-				if (commandHelpTarget !== null) {
-					const entry = findCommandHelp(commandHelpTarget);
-					if (entry !== void 0) {
-						stdout(`${renderCommandHelpText({ entry })}\n`);
-						return EXIT_CODE.OK;
-					}
-				}
-				stdout(`${renderGeneralHelpText({ version })}\n`);
-				return EXIT_CODE.OK;
-			}
-			if (parsedArgs.version === true) {
-				stdout(version);
-				return EXIT_CODE.OK;
-			}
+			const readOnlyDispatch = await dispatchReadOnlyCommands({
+				command,
+				commandArgs,
+				positionals,
+				parsedArgs: parsedArgsRecord,
+				jsonEnabled,
+				version,
+				availableCommandNames: commandHelpNames,
+				stdout,
+				findCommandHelp,
+				renderGeneralHelpText,
+				renderCommandHelpText,
+				ensureArgumentCount,
+				resolveCompletionShell,
+				loadCompletionScript,
+				resolveCompletionInstallPath,
+				installCompletionScript,
+				readStringOption,
+				buildJsonSuccess
+			});
+			if (readOnlyDispatch.handled) return readOnlyDispatch.exitCode;
 			logger = parsedArgs.verbose === true ? createLogger({ level: LogLevel.INFO }) : createLogger();
-			if (positionals.length === 0) {
-				stdout(`${renderGeneralHelpText({ version })}\n`);
-				return EXIT_CODE.OK;
-			}
-			if (command === "help") {
-				const helpTarget = positionals[1];
-				if (typeof helpTarget !== "string" || helpTarget.length === 0) {
-					stdout(`${renderGeneralHelpText({ version })}\n`);
-					return EXIT_CODE.OK;
-				}
-				const entry = findCommandHelp(helpTarget);
-				if (entry === void 0) throw createCliError("INVALID_ARGUMENT", {
-					message: `Unknown command for help: ${helpTarget}`,
-					details: {
-						requested: helpTarget,
-						availableCommands: commandHelpEntries.map((item) => item.name)
-					}
-				});
-				stdout(`${renderCommandHelpText({ entry })}\n`);
-				return EXIT_CODE.OK;
-			}
-			const commandArgs = positionals.slice(1);
-			if (command === "completion") {
-				ensureArgumentCount({
-					command,
-					args: commandArgs,
-					min: 1,
-					max: 1
-				});
-				const shell = resolveCompletionShell(commandArgs[0]);
-				const script = await loadCompletionScript(shell);
-				if (parsedArgs.install === true) {
-					const destinationPath = resolveCompletionInstallPath({
-						shell,
-						requestedPath: readStringOption(parsedArgsRecord, "path")
-					});
-					await installCompletionScript({
-						content: script,
-						destinationPath
-					});
-					if (jsonEnabled) {
-						stdout(JSON.stringify(buildJsonSuccess({
-							command,
-							status: "ok",
-							repoRoot: null,
-							details: {
-								shell,
-								installed: true,
-								path: destinationPath
-							}
-						})));
-						return EXIT_CODE.OK;
-					}
-					stdout(`installed completion: ${destinationPath}`);
-					if (shell === "zsh") stdout("zsh note: ensure completion path is in fpath, then run: autoload -Uz compinit && compinit");
-					return EXIT_CODE.OK;
-				}
-				if (jsonEnabled) {
-					stdout(JSON.stringify(buildJsonSuccess({
-						command,
-						status: "ok",
-						repoRoot: null,
-						details: {
-							shell,
-							installed: false,
-							script
-						}
-					})));
-					return EXIT_CODE.OK;
-				}
-				stdout(script);
-				return EXIT_CODE.OK;
-			}
 			const allowUnsafe = parsedArgs.allowUnsafe === true;
 			if (parsedArgs.hooks === false && allowUnsafe !== true) throw createCliError("UNSAFE_FLAG_REQUIRED", { message: "UNSAFE_FLAG_REQUIRED: --no-hooks requires --allow-unsafe" });
 			const repoContext = await resolveRepoContext(runtimeCwd);
 			const repoRoot = repoContext.repoRoot;
 			repoRootForJson = repoRoot;
-			const configuredHookTimeoutMs = await readGitConfigInt(repoRoot, "vde-worktree.hookTimeoutMs");
-			const configuredLockTimeoutMs = await readGitConfigInt(repoRoot, "vde-worktree.lockTimeoutMs");
-			const configuredStaleTTL = await readGitConfigInt(repoRoot, "vde-worktree.staleLockTTLSeconds");
-			const configuredHooksEnabled = await readGitConfigBoolean(repoRoot, "vde-worktree.hooksEnabled");
+			const { config: resolvedConfig } = await loadResolvedConfig({
+				cwd: runtimeCwd,
+				repoRoot
+			});
+			const managedWorktreeRoot = getWorktreeRootPath(repoRoot, resolvedConfig.paths.worktreeRoot);
 			const runtime = {
 				command,
 				json: jsonEnabled,
-				hooksEnabled: parsedArgs.hooks !== false && configuredHooksEnabled !== false,
-				ghEnabled: parsedArgs.gh !== false,
+				hooksEnabled: parsedArgs.hooks !== false && resolvedConfig.hooks.enabled,
+				ghEnabled: parsedArgs.gh !== false && resolvedConfig.github.enabled,
 				strictPostHooks: parsedArgs.strictPostHooks === true,
 				hookTimeoutMs: readNumberFromEnvOrDefault({
 					rawValue: toNumberOption({
 						value: parsedArgs.hookTimeoutMs,
 						optionName: "--hook-timeout-ms"
-					}) ?? configuredHookTimeoutMs,
+					}) ?? resolvedConfig.hooks.timeoutMs,
 					defaultValue: DEFAULT_HOOK_TIMEOUT_MS
 				}),
 				lockTimeoutMs: readNumberFromEnvOrDefault({
 					rawValue: toNumberOption({
 						value: parsedArgs.lockTimeoutMs,
 						optionName: "--lock-timeout-ms"
-					}) ?? configuredLockTimeoutMs,
+					}) ?? resolvedConfig.locks.timeoutMs,
 					defaultValue: DEFAULT_LOCK_TIMEOUT_MS
 				}),
 				allowUnsafe,
 				isInteractive: isInteractiveFn()
 			};
 			const staleLockTTLSeconds = readNumberFromEnvOrDefault({
-				rawValue: configuredStaleTTL,
+				rawValue: resolvedConfig.locks.staleLockTTLSeconds,
 				defaultValue: DEFAULT_STALE_LOCK_TTL_SECONDS
 			});
 			const collectWorktreeSnapshot$1 = async (_ignoredRepoRoot) => {
-				return collectWorktreeSnapshot(repoRoot, { noGh: runtime.ghEnabled !== true });
+				return collectWorktreeSnapshot(repoRoot, {
+					baseBranch: await resolveBaseBranch({
+						repoRoot,
+						config: resolvedConfig
+					}),
+					ghEnabled: runtime.ghEnabled,
+					noGh: runtime.ghEnabled !== true
+				});
 			};
 			const runWriteOperation = async (task) => {
 				if (WRITE_COMMANDS.has(command) !== true) return task();
@@ -3071,7 +4038,30 @@ const createCli = (options = {}) => {
 					staleLockTTLSeconds
 				}, task);
 			};
-			if (command === "init") {
+			const executeWorktreeMutation = async ({ name, branch, worktreePath, extraEnv, precheck, runGit, finalize }) => {
+				const precheckResult = await precheck();
+				const hookContext = createHookContext({
+					runtime,
+					repoRoot,
+					action: name,
+					branch,
+					worktreePath,
+					stderr,
+					extraEnv
+				});
+				await runPreHook({
+					name,
+					context: hookContext
+				});
+				const result = await runGit(precheckResult);
+				if (finalize !== void 0) await finalize(precheckResult, result);
+				await runPostHook({
+					name,
+					context: hookContext
+				});
+				return result;
+			};
+			const handleInit = async () => {
 				ensureArgumentCount({
 					command,
 					args: commandArgs,
@@ -3091,28 +4081,28 @@ const createCli = (options = {}) => {
 						name: "init",
 						context: hookContext
 					});
-					const initialized = await initializeRepository(repoRoot);
+					const initialized = await initializeRepository({
+						repoRoot,
+						managedWorktreeRoot
+					});
 					await runPostHook({
 						name: "init",
 						context: hookContext
 					});
 					return initialized;
 				});
-				if (runtime.json) {
-					stdout(JSON.stringify(buildJsonSuccess({
-						command,
-						status: "ok",
-						repoRoot,
-						details: {
-							initialized: true,
-							alreadyInitialized: result.alreadyInitialized
-						}
-					})));
-					return EXIT_CODE.OK;
-				}
+				if (runtime.json) stdout(JSON.stringify(buildJsonSuccess({
+					command,
+					status: "ok",
+					repoRoot,
+					details: {
+						initialized: true,
+						alreadyInitialized: result.alreadyInitialized
+					}
+				})));
 				return EXIT_CODE.OK;
-			}
-			if (command === "list") {
+			};
+			const handleList = async () => {
 				ensureArgumentCount({
 					command,
 					args: commandArgs,
@@ -3127,22 +4117,15 @@ const createCli = (options = {}) => {
 						repoRoot,
 						details: {
 							baseBranch: snapshot.baseBranch,
+							managedWorktreeRoot,
 							worktrees: snapshot.worktrees
 						}
 					})));
 					return EXIT_CODE.OK;
 				}
 				const theme = createCatppuccinTheme({ enabled: shouldUseAnsiColors({ interactive: runtime.isInteractive }) });
-				const rows = [[
-					"branch",
-					"dirty",
-					"merged",
-					"pr",
-					"locked",
-					"ahead",
-					"behind",
-					"path"
-				], ...await Promise.all(snapshot.worktrees.map(async (worktree) => {
+				const columns = resolvedConfig.list.table.columns;
+				const rows = [[...columns], ...await Promise.all(snapshot.worktrees.map(async (worktree) => {
 					const distanceFromBase = await resolveAheadBehindAgainstBaseBranch({
 						repoRoot,
 						baseBranch: snapshot.baseBranch,
@@ -3154,39 +4137,45 @@ const createCli = (options = {}) => {
 						prStatus: worktree.pr.status,
 						isBaseBranch
 					});
-					return [
-						`${worktree.path === repoContext.currentWorktreeRoot ? "*" : " "} ${worktree.branch ?? "(detached)"}`,
-						worktree.dirty ? "dirty" : "clean",
-						mergedState,
-						prState,
-						worktree.locked.value ? "locked" : "-",
-						formatListUpstreamCount(distanceFromBase.ahead),
-						formatListUpstreamCount(distanceFromBase.behind),
-						formatDisplayPath(worktree.path)
-					];
+					const valuesByColumn = {
+						branch: `${worktree.path === repoContext.currentWorktreeRoot ? "*" : " "} ${worktree.branch ?? "(detached)"}`,
+						dirty: worktree.dirty ? "dirty" : "clean",
+						merged: mergedState,
+						pr: prState,
+						locked: worktree.locked.value ? "locked" : "-",
+						ahead: formatListUpstreamCount(distanceFromBase.ahead),
+						behind: formatListUpstreamCount(distanceFromBase.behind),
+						path: formatDisplayPath(worktree.path)
+					};
+					return columns.map((column) => valuesByColumn[column]);
 				}))];
 				const pathColumnWidth = resolveListPathColumnWidth({
 					rows,
-					disablePathTruncation: parsedArgs.fullPath === true
+					columns,
+					truncateMode: resolvedConfig.list.table.path.truncate,
+					fullPath: parsedArgs.fullPath === true,
+					minWidth: resolvedConfig.list.table.path.minWidth
 				});
-				const columnsConfig = pathColumnWidth === null ? void 0 : { [LIST_TABLE_PATH_COLUMN_INDEX]: {
+				const pathColumnIndex = columns.indexOf("path");
+				const columnsConfig = pathColumnWidth === null || pathColumnIndex < 0 ? void 0 : { [pathColumnIndex]: {
 					width: pathColumnWidth,
 					truncate: pathColumnWidth
 				} };
-				const colorized = colorizeListTable({
-					rendered: table(rows, {
-						border: getBorderCharacters("norc"),
-						drawHorizontalLine: (lineIndex, rowCount) => {
-							return lineIndex === 0 || lineIndex === 1 || lineIndex === rowCount;
-						},
-						columns: columnsConfig
-					}),
-					theme
+				const rendered = table(rows, {
+					border: getBorderCharacters("norc"),
+					drawHorizontalLine: (lineIndex, rowCount) => {
+						return lineIndex === 0 || lineIndex === 1 || lineIndex === rowCount;
+					},
+					columns: columnsConfig
 				});
+				const colorized = hasDefaultListColumnOrder(columns) ? colorizeListTable({
+					rendered,
+					theme
+				}) : rendered.trimEnd();
 				for (const line of colorized.split("\n")) stdout(line);
 				return EXIT_CODE.OK;
-			}
-			if (command === "status") {
+			};
+			const handleStatus = async () => {
 				ensureArgumentCount({
 					command,
 					args: commandArgs,
@@ -3216,8 +4205,8 @@ const createCli = (options = {}) => {
 				stdout(`dirty: ${targetWorktree.dirty ? "true" : "false"}`);
 				stdout(`locked: ${targetWorktree.locked.value ? "true" : "false"}`);
 				return EXIT_CODE.OK;
-			}
-			if (command === "path") {
+			};
+			const handlePath = async () => {
 				ensureArgumentCount({
 					command,
 					args: commandArgs,
@@ -3243,8 +4232,18 @@ const createCli = (options = {}) => {
 				}
 				stdout(target.path);
 				return EXIT_CODE.OK;
-			}
-			if (command === "new") {
+			};
+			const earlyRepoExitCode = await dispatchCommandHandler({
+				command,
+				handlers: createEarlyRepoCommandHandlers({
+					initHandler: handleInit,
+					listHandler: handleList,
+					statusHandler: handleStatus,
+					pathHandler: handlePath
+				})
+			});
+			if (earlyRepoExitCode !== void 0) return earlyRepoExitCode;
+			const handleNew = async () => {
 				ensureArgumentCount({
 					command,
 					args: commandArgs,
@@ -3252,58 +4251,56 @@ const createCli = (options = {}) => {
 					max: 1
 				});
 				const branch = commandArgs[0] ?? randomWipBranchName();
+				const targetPath = branchToWorktreePath(repoRoot, branch, resolvedConfig.paths.worktreeRoot);
 				const result = await runWriteOperation(async () => {
-					if (containsBranch({
-						branch,
-						worktrees: (await collectWorktreeSnapshot$1(repoRoot)).worktrees
-					})) throw createCliError("BRANCH_ALREADY_ATTACHED", {
-						message: `Branch is already attached to a worktree: ${branch}`,
-						details: { branch }
-					});
-					if (await doesGitRefExist(repoRoot, `refs/heads/${branch}`)) throw createCliError("BRANCH_ALREADY_EXISTS", {
-						message: `Branch already exists locally: ${branch}`,
-						details: { branch }
-					});
-					const targetPath = branchToWorktreePath(repoRoot, branch);
-					await ensureTargetPathWritable(targetPath);
-					const baseBranch = await resolveBaseBranch(repoRoot);
-					const hookContext = createHookContext({
-						runtime,
-						repoRoot,
-						action: "new",
-						branch,
-						worktreePath: targetPath,
-						stderr
-					});
-					await runPreHook({
+					return executeWorktreeMutation({
 						name: "new",
-						context: hookContext
-					});
-					await runGitCommand({
-						cwd: repoRoot,
-						args: [
-							"worktree",
-							"add",
-							"-b",
-							branch,
-							targetPath,
-							baseBranch
-						]
-					});
-					await upsertWorktreeMergeLifecycle({
-						repoRoot,
 						branch,
-						baseBranch,
-						observedDivergedHead: null
-					});
-					await runPostHook({
-						name: "new",
-						context: hookContext
+						worktreePath: targetPath,
+						precheck: async () => {
+							if (containsBranch({
+								branch,
+								worktrees: (await collectWorktreeSnapshot$1(repoRoot)).worktrees
+							})) throw createCliError("BRANCH_ALREADY_ATTACHED", {
+								message: `Branch is already attached to a worktree: ${branch}`,
+								details: { branch }
+							});
+							if (await doesGitRefExist(repoRoot, `refs/heads/${branch}`)) throw createCliError("BRANCH_ALREADY_EXISTS", {
+								message: `Branch already exists locally: ${branch}`,
+								details: { branch }
+							});
+							await ensureTargetPathWritable(targetPath);
+							return { baseBranch: await resolveBaseBranch({
+								repoRoot,
+								config: resolvedConfig
+							}) };
+						},
+						runGit: async ({ baseBranch }) => {
+							await runGitCommand({
+								cwd: repoRoot,
+								args: [
+									"worktree",
+									"add",
+									"-b",
+									branch,
+									targetPath,
+									baseBranch
+								]
+							});
+							return {
+								branch,
+								path: targetPath
+							};
+						},
+						finalize: async ({ baseBranch }) => {
+							await upsertWorktreeMergeLifecycle({
+								repoRoot,
+								branch,
+								baseBranch,
+								observedDivergedHead: null
+							});
+						}
 					});
-					return {
-						branch,
-						path: targetPath
-					};
 				});
 				if (runtime.json) {
 					stdout(JSON.stringify(buildJsonSuccess({
@@ -3316,8 +4313,8 @@ const createCli = (options = {}) => {
 				}
 				stdout(result.path);
 				return EXIT_CODE.OK;
-			}
-			if (command === "switch") {
+			};
+			const handleSwitch = async () => {
 				ensureArgumentCount({
 					command,
 					args: commandArgs,
@@ -3327,74 +4324,72 @@ const createCli = (options = {}) => {
 				const branch = commandArgs[0];
 				const result = await runWriteOperation(async () => {
 					const snapshot = await collectWorktreeSnapshot$1(repoRoot);
-					const existing = snapshot.worktrees.find((worktree) => worktree.branch === branch);
-					if (existing !== void 0) {
-						if (snapshot.baseBranch !== null) await upsertWorktreeMergeLifecycle({
-							repoRoot,
-							branch,
-							baseBranch: snapshot.baseBranch,
-							observedDivergedHead: null
-						});
-						return {
-							status: "existing",
-							branch,
-							path: existing.path
-						};
-					}
-					const targetPath = branchToWorktreePath(repoRoot, branch);
-					await ensureTargetPathWritable(targetPath);
-					const hookContext = createHookContext({
-						runtime,
-						repoRoot,
-						action: "switch",
-						branch,
-						worktreePath: targetPath,
-						stderr
-					});
-					await runPreHook({
-						name: "switch",
-						context: hookContext
-					});
-					let lifecycleBaseBranch = snapshot.baseBranch;
-					if (await doesGitRefExist(repoRoot, `refs/heads/${branch}`)) await runGitCommand({
-						cwd: repoRoot,
-						args: [
-							"worktree",
-							"add",
-							targetPath,
-							branch
-						]
-					});
-					else {
-						const baseBranch = await resolveBaseBranch(repoRoot);
-						lifecycleBaseBranch = baseBranch;
-						await runGitCommand({
-							cwd: repoRoot,
-							args: [
-								"worktree",
-								"add",
-								"-b",
-								branch,
-								targetPath,
-								baseBranch
-							]
+					const existing = snapshot.worktrees.find((worktree) => worktree.branch === branch);
+					if (existing !== void 0) {
+						if (snapshot.baseBranch !== null) await upsertWorktreeMergeLifecycle({
+							repoRoot,
+							branch,
+							baseBranch: snapshot.baseBranch,
+							observedDivergedHead: null
 						});
+						return {
+							status: "existing",
+							branch,
+							path: existing.path
+						};
 					}
-					if (lifecycleBaseBranch !== null) await upsertWorktreeMergeLifecycle({
-						repoRoot,
-						branch,
-						baseBranch: lifecycleBaseBranch,
-						observedDivergedHead: null
-					});
-					await runPostHook({
+					const targetPath = branchToWorktreePath(repoRoot, branch, resolvedConfig.paths.worktreeRoot);
+					return executeWorktreeMutation({
 						name: "switch",
-						context: hookContext
-					});
-					return {
-						status: "created",
 						branch,
-						path: targetPath
-					};
+						worktreePath: targetPath,
+						precheck: async () => {
+							await ensureTargetPathWritable(targetPath);
+							if (await doesGitRefExist(repoRoot, `refs/heads/${branch}`)) return {
+								gitArgs: [
+									"worktree",
+									"add",
+									targetPath,
+									branch
+								],
+								lifecycleBaseBranch: snapshot.baseBranch
+							};
+							const baseBranch = await resolveBaseBranch({
+								repoRoot,
+								config: resolvedConfig
+							});
+							return {
+								gitArgs: [
+									"worktree",
+									"add",
+									"-b",
+									branch,
+									targetPath,
+									baseBranch
+								],
+								lifecycleBaseBranch: baseBranch
+							};
+						},
+						runGit: async ({ gitArgs }) => {
+							await runGitCommand({
+								cwd: repoRoot,
+								args: [...gitArgs]
+							});
+							return {
+								status: "created",
+								branch,
+								path: targetPath
+							};
+						},
+						finalize: async ({ lifecycleBaseBranch }) => {
+							if (lifecycleBaseBranch !== null) await upsertWorktreeMergeLifecycle({
+								repoRoot,
+								branch,
+								baseBranch: lifecycleBaseBranch,
+								observedDivergedHead: null
+							});
+						}
+					});
 				});
 				if (runtime.json) {
 					stdout(JSON.stringify(buildJsonSuccess({
@@ -3410,8 +4405,16 @@ const createCli = (options = {}) => {
 				}
 				stdout(result.path);
 				return EXIT_CODE.OK;
-			}
-			if (command === "mv") {
+			};
+			const writeCommandExitCode = await dispatchCommandHandler({
+				command,
+				handlers: createWriteCommandHandlers({
+					newHandler: handleNew,
+					switchHandler: handleSwitch
+				})
+			});
+			if (writeCommandExitCode !== void 0) return writeCommandExitCode;
+			const handleMv = async () => {
 				ensureArgumentCount({
 					command,
 					args: commandArgs,
@@ -3438,68 +4441,68 @@ const createCli = (options = {}) => {
 						branch: newBranch,
 						path: current.path
 					};
-					if (containsBranch({
-						branch: newBranch,
-						worktrees: snapshot.worktrees
-					})) throw createCliError("BRANCH_ALREADY_ATTACHED", {
-						message: `Branch is already attached to another worktree: ${newBranch}`,
-						details: { branch: newBranch }
-					});
-					if (await doesGitRefExist(repoRoot, `refs/heads/${newBranch}`)) throw createCliError("BRANCH_ALREADY_EXISTS", {
-						message: `Branch already exists locally: ${newBranch}`,
-						details: { branch: newBranch }
-					});
-					const newPath = branchToWorktreePath(repoRoot, newBranch);
-					await ensureTargetPathWritable(newPath);
-					const hookContext = createHookContext({
-						runtime,
-						repoRoot,
-						action: "mv",
+					const newPath = branchToWorktreePath(repoRoot, newBranch, resolvedConfig.paths.worktreeRoot);
+					return executeWorktreeMutation({
+						name: "mv",
 						branch: newBranch,
 						worktreePath: newPath,
-						stderr,
 						extraEnv: {
 							WT_OLD_BRANCH: oldBranch,
 							WT_NEW_BRANCH: newBranch
+						},
+						precheck: async () => {
+							if (containsBranch({
+								branch: newBranch,
+								worktrees: snapshot.worktrees
+							})) throw createCliError("BRANCH_ALREADY_ATTACHED", {
+								message: `Branch is already attached to another worktree: ${newBranch}`,
+								details: { branch: newBranch }
+							});
+							if (await doesGitRefExist(repoRoot, `refs/heads/${newBranch}`)) throw createCliError("BRANCH_ALREADY_EXISTS", {
+								message: `Branch already exists locally: ${newBranch}`,
+								details: { branch: newBranch }
+							});
+							await ensureTargetPathWritable(newPath);
+							return {
+								oldBranch,
+								currentPath: current.path,
+								baseBranch: snapshot.baseBranch
+							};
+						},
+						runGit: async ({ oldBranch: resolvedOldBranch, currentPath }) => {
+							await runGitCommand({
+								cwd: currentPath,
+								args: [
+									"branch",
+									"-m",
+									resolvedOldBranch,
+									newBranch
+								]
+							});
+							await runGitCommand({
+								cwd: repoRoot,
+								args: [
+									"worktree",
+									"move",
+									currentPath,
+									newPath
+								]
+							});
+							return {
+								branch: newBranch,
+								path: newPath
+							};
+						},
+						finalize: async ({ oldBranch: resolvedOldBranch, baseBranch }) => {
+							if (baseBranch !== null) await moveWorktreeMergeLifecycle({
+								repoRoot,
+								fromBranch: resolvedOldBranch,
+								toBranch: newBranch,
+								baseBranch,
+								observedDivergedHead: null
+							});
 						}
 					});
-					await runPreHook({
-						name: "mv",
-						context: hookContext
-					});
-					await runGitCommand({
-						cwd: current.path,
-						args: [
-							"branch",
-							"-m",
-							oldBranch,
-							newBranch
-						]
-					});
-					await runGitCommand({
-						cwd: repoRoot,
-						args: [
-							"worktree",
-							"move",
-							current.path,
-							newPath
-						]
-					});
-					if (snapshot.baseBranch !== null) await moveWorktreeMergeLifecycle({
-						repoRoot,
-						fromBranch: oldBranch,
-						toBranch: newBranch,
-						baseBranch: snapshot.baseBranch,
-						observedDivergedHead: null
-					});
-					await runPostHook({
-						name: "mv",
-						context: hookContext
-					});
-					return {
-						branch: newBranch,
-						path: newPath
-					};
 				});
 				if (runtime.json) {
 					stdout(JSON.stringify(buildJsonSuccess({
@@ -3512,8 +4515,8 @@ const createCli = (options = {}) => {
 				}
 				stdout(result.path);
 				return EXIT_CODE.OK;
-			}
-			if (command === "del") {
+			};
+			const handleDel = async () => {
 				ensureArgumentCount({
 					command,
 					args: commandArgs,
@@ -3543,56 +4546,69 @@ const createCli = (options = {}) => {
 						message: "Cannot delete the primary worktree",
 						details: { path: target.path }
 					});
-					validateDeleteSafety({
-						target,
-						forceFlags
-					});
-					const hookContext = createHookContext({
-						runtime,
-						repoRoot,
-						action: "del",
-						branch: target.branch,
+					if (isManagedWorktreePath({
 						worktreePath: target.path,
-						stderr
-					});
-					await runPreHook({
-						name: "del",
-						context: hookContext
-					});
-					const removeArgs = [
-						"worktree",
-						"remove",
-						target.path
-					];
-					if (forceFlags.forceDirty) removeArgs.push("--force");
-					await runGitCommand({
-						cwd: repoRoot,
-						args: removeArgs
-					});
-					await runGitCommand({
-						cwd: repoRoot,
-						args: [
-							"branch",
-							resolveBranchDeleteMode(forceFlags),
-							target.branch
-						]
-					});
-					await deleteWorktreeLock({
-						repoRoot,
-						branch: target.branch
-					});
-					await deleteWorktreeMergeLifecycle({
-						repoRoot,
-						branch: target.branch
+						managedWorktreeRoot
+					}) !== true) throw createCliError("WORKTREE_NOT_FOUND", {
+						message: "Target branch is not in managed worktree root",
+						details: {
+							branch: target.branch,
+							path: target.path,
+							managedWorktreeRoot
+						}
 					});
-					await runPostHook({
+					const targetBranch = target.branch;
+					return executeWorktreeMutation({
 						name: "del",
-						context: hookContext
+						branch: targetBranch,
+						worktreePath: target.path,
+						precheck: async () => {
+							validateDeleteSafety({
+								target,
+								forceFlags
+							});
+							const removeArgs = [
+								"worktree",
+								"remove",
+								target.path
+							];
+							if (forceFlags.forceDirty) removeArgs.push("--force");
+							return {
+								branch: targetBranch,
+								path: target.path,
+								removeArgs,
+								branchDeleteMode: resolveBranchDeleteMode(forceFlags)
+							};
+						},
+						runGit: async ({ branch: targetBranch, removeArgs, branchDeleteMode, path }) => {
+							await runGitCommand({
+								cwd: repoRoot,
+								args: removeArgs
+							});
+							await runGitCommand({
+								cwd: repoRoot,
+								args: [
+									"branch",
+									branchDeleteMode,
+									targetBranch
+								]
+							});
+							return {
+								branch: targetBranch,
+								path
+							};
+						},
+						finalize: async ({ branch: targetBranch }) => {
+							await deleteWorktreeLock({
+								repoRoot,
+								branch: targetBranch
+							});
+							await deleteWorktreeMergeLifecycle({
+								repoRoot,
+								branch: targetBranch
+							});
+						}
 					});
-					return {
-						branch: target.branch,
-						path: target.path
-					};
 				});
 				if (runtime.json) {
 					stdout(JSON.stringify(buildJsonSuccess({
@@ -3605,8 +4621,16 @@ const createCli = (options = {}) => {
 				}
 				stdout(result.path);
 				return EXIT_CODE.OK;
-			}
-			if (command === "gone") {
+			};
+			const writeMutationExitCode = await dispatchCommandHandler({
+				command,
+				handlers: createWriteMutationHandlers({
+					mvHandler: handleMv,
+					delHandler: handleDel
+				})
+			});
+			if (writeMutationExitCode !== void 0) return writeMutationExitCode;
+			const handleGone = async () => {
 				ensureArgumentCount({
 					command,
 					args: commandArgs,
@@ -3616,7 +4640,10 @@ const createCli = (options = {}) => {
 				if (parsedArgs.apply === true && parsedArgs.dryRun === true) throw createCliError("INVALID_ARGUMENT", { message: "Cannot use --apply and --dry-run together" });
 				const dryRun = parsedArgs.apply !== true;
 				const execute = async () => {
-					const candidates = (await collectWorktreeSnapshot$1(repoRoot)).worktrees.filter((worktree) => worktree.branch !== null).filter((worktree) => worktree.path !== repoRoot).filter((worktree) => worktree.dirty === false).filter((worktree) => worktree.locked.value === false).filter((worktree) => worktree.merged.overall === true).map((worktree) => worktree.branch);
+					const candidates = (await collectWorktreeSnapshot$1(repoRoot)).worktrees.filter((worktree) => worktree.branch !== null).filter((worktree) => worktree.path !== repoRoot).filter((worktree) => isManagedWorktreePath({
+						worktreePath: worktree.path,
+						managedWorktreeRoot
+					})).filter((worktree) => worktree.dirty === false).filter((worktree) => worktree.locked.value === false).filter((worktree) => worktree.merged.overall === true).map((worktree) => worktree.branch);
 					if (dryRun) return {
 						deleted: [],
 						candidates,
@@ -3693,8 +4720,8 @@ const createCli = (options = {}) => {
 				const branches = result.dryRun ? result.candidates : result.deleted;
 				for (const branch of branches) stdout(`${label}: ${branch}`);
 				return EXIT_CODE.OK;
-			}
-			if (command === "get") {
+			};
+			const handleGet = async () => {
 				ensureArgumentCount({
 					command,
 					args: commandArgs,
@@ -3721,7 +4748,7 @@ const createCli = (options = {}) => {
 						repoRoot,
 						action: "get",
 						branch,
-						worktreePath: branchToWorktreePath(repoRoot, branch),
+						worktreePath: branchToWorktreePath(repoRoot, branch, resolvedConfig.paths.worktreeRoot),
 						stderr
 					});
 					await runPreHook({
@@ -3772,7 +4799,7 @@ const createCli = (options = {}) => {
 							path: existing.path
 						};
 					}
-					const targetPath = branchToWorktreePath(repoRoot, branch);
+					const targetPath = branchToWorktreePath(repoRoot, branch, resolvedConfig.paths.worktreeRoot);
 					await ensureTargetPathWritable(targetPath);
 					await runGitCommand({
 						cwd: repoRoot,
@@ -3813,8 +4840,8 @@ const createCli = (options = {}) => {
 				}
 				stdout(result.path);
 				return EXIT_CODE.OK;
-			}
-			if (command === "extract") {
+			};
+			const handleExtract = async () => {
 				ensureArgumentCount({
 					command,
 					args: commandArgs,
@@ -3846,12 +4873,15 @@ const createCli = (options = {}) => {
 						details: { path: sourceWorktree.path }
 					});
 					const branch = sourceWorktree.branch;
-					const baseBranch = await resolveBaseBranch(repoRoot);
+					const baseBranch = await resolveBaseBranch({
+						repoRoot,
+						config: resolvedConfig
+					});
 					ensureBranchIsNotPrimary({
 						branch,
 						baseBranch
 					});
-					const targetPath = branchToWorktreePath(repoRoot, branch);
+					const targetPath = branchToWorktreePath(repoRoot, branch, resolvedConfig.paths.worktreeRoot);
 					await ensureTargetPathWritable(targetPath);
 					const dirty = (await runGitCommand({
 						cwd: repoRoot,
@@ -3943,8 +4973,17 @@ const createCli = (options = {}) => {
 				}
 				stdout(result.path);
 				return EXIT_CODE.OK;
-			}
-			if (command === "absorb") {
+			};
+			const worktreeActionExitCode = await dispatchCommandHandler({
+				command,
+				handlers: createWorktreeActionHandlers({
+					goneHandler: handleGone,
+					getHandler: handleGet,
+					extractHandler: handleExtract
+				})
+			});
+			if (worktreeActionExitCode !== void 0) return worktreeActionExitCode;
+			const handleAbsorb = async () => {
 				ensureArgumentCount({
 					command,
 					args: commandArgs,
@@ -3972,6 +5011,7 @@ const createCli = (options = {}) => {
 					});
 					const sourceWorktree = resolveManagedNonPrimaryWorktreeByBranch({
 						repoRoot,
+						managedWorktreeRoot,
 						branch,
 						worktrees: (await collectWorktreeSnapshot$1(repoRoot)).worktrees,
 						optionName: "--from",
@@ -4065,8 +5105,8 @@ const createCli = (options = {}) => {
 				}
 				stdout(result.path);
 				return EXIT_CODE.OK;
-			}
-			if (command === "unabsorb") {
+			};
+			const handleUnabsorb = async () => {
 				ensureArgumentCount({
 					command,
 					args: commandArgs,
@@ -4106,6 +5146,7 @@ const createCli = (options = {}) => {
 					});
 					const targetWorktree = resolveManagedNonPrimaryWorktreeByBranch({
 						repoRoot,
+						managedWorktreeRoot,
 						branch,
 						worktrees: (await collectWorktreeSnapshot$1(repoRoot)).worktrees,
 						optionName: "--to",
@@ -4197,8 +5238,8 @@ const createCli = (options = {}) => {
 				}
 				stdout(result.path);
 				return EXIT_CODE.OK;
-			}
-			if (command === "use") {
+			};
+			const handleUse = async () => {
 				ensureArgumentCount({
 					command,
 					args: commandArgs,
@@ -4291,8 +5332,17 @@ const createCli = (options = {}) => {
 				}
 				stdout(result.path);
 				return EXIT_CODE.OK;
-			}
-			if (command === "exec") {
+			};
+			const synchronizationExitCode = await dispatchCommandHandler({
+				command,
+				handlers: createSynchronizationHandlers({
+					absorbHandler: handleAbsorb,
+					unabsorbHandler: handleUnabsorb,
+					useHandler: handleUse
+				})
+			});
+			if (synchronizationExitCode !== void 0) return synchronizationExitCode;
+			const handleExec = async () => {
 				ensureArgumentCount({
 					command,
 					args: commandArgs,
@@ -4347,8 +5397,8 @@ const createCli = (options = {}) => {
 					return EXIT_CODE.CHILD_PROCESS_FAILED;
 				}
 				return childExitCode === 0 ? EXIT_CODE.OK : EXIT_CODE.CHILD_PROCESS_FAILED;
-			}
-			if (command === "invoke") {
+			};
+			const handleInvoke = async () => {
 				ensureArgumentCount({
 					command,
 					args: commandArgs,
@@ -4372,38 +5422,32 @@ const createCli = (options = {}) => {
 						stderr
 					})
 				});
-				if (runtime.json) {
-					stdout(JSON.stringify(buildJsonSuccess({
-						command,
-						status: "ok",
-						repoRoot,
-						details: {
-							hook: hookName,
-							exitCode: 0
-						}
-					})));
-					return EXIT_CODE.OK;
-				}
+				if (runtime.json) stdout(JSON.stringify(buildJsonSuccess({
+					command,
+					status: "ok",
+					repoRoot,
+					details: {
+						hook: hookName,
+						exitCode: 0
+					}
+				})));
 				return EXIT_CODE.OK;
-			}
-			if (command === "copy") {
+			};
+			const handleCopy = async () => {
 				ensureArgumentCount({
 					command,
 					args: commandArgs,
 					min: 1,
 					max: Number.MAX_SAFE_INTEGER
 				});
-				const worktreePath = ensurePathInsideRepo({
-					repoRoot,
-					path: resolvePathFromCwd({
-						cwd: repoContext.currentWorktreeRoot,
-						path: process.env.WT_WORKTREE_PATH ?? "."
-					})
+				const targetWorktreeRoot = resolveTargetWorktreeRootForCopyLink({
+					repoContext,
+					snapshot: await collectWorktreeSnapshot$1(repoRoot)
 				});
 				for (const relativePath of commandArgs) {
 					const { sourcePath, destinationPath } = resolveFileCopyTargets({
 						repoRoot,
-						worktreePath,
+						targetWorktreeRoot,
 						relativePath
 					});
 					await access(sourcePath, constants.F_OK);
@@ -4415,39 +5459,33 @@ const createCli = (options = {}) => {
 						dereference: false
 					});
 				}
-				if (runtime.json) {
-					stdout(JSON.stringify(buildJsonSuccess({
-						command,
-						status: "ok",
-						repoRoot,
-						details: {
-							copied: commandArgs,
-							worktreePath
-						}
-					})));
-					return EXIT_CODE.OK;
-				}
+				if (runtime.json) stdout(JSON.stringify(buildJsonSuccess({
+					command,
+					status: "ok",
+					repoRoot,
+					details: {
+						copied: commandArgs,
+						worktreePath: targetWorktreeRoot
+					}
+				})));
 				return EXIT_CODE.OK;
-			}
-			if (command === "link") {
+			};
+			const handleLink = async () => {
 				ensureArgumentCount({
 					command,
 					args: commandArgs,
 					min: 1,
 					max: Number.MAX_SAFE_INTEGER
 				});
-				const worktreePath = ensurePathInsideRepo({
-					repoRoot,
-					path: resolvePathFromCwd({
-						cwd: repoContext.currentWorktreeRoot,
-						path: process.env.WT_WORKTREE_PATH ?? "."
-					})
+				const targetWorktreeRoot = resolveTargetWorktreeRootForCopyLink({
+					repoContext,
+					snapshot: await collectWorktreeSnapshot$1(repoRoot)
 				});
 				const fallbackEnabled = parsedArgs.fallback !== false;
 				for (const relativePath of commandArgs) {
 					const { sourcePath, destinationPath } = resolveFileCopyTargets({
 						repoRoot,
-						worktreePath,
+						targetWorktreeRoot,
 						relativePath
 					});
 					await access(sourcePath, constants.F_OK);
@@ -4478,22 +5516,19 @@ const createCli = (options = {}) => {
 						});
 					}
 				}
-				if (runtime.json) {
-					stdout(JSON.stringify(buildJsonSuccess({
-						command,
-						status: "ok",
-						repoRoot,
-						details: {
-							linked: commandArgs,
-							worktreePath,
-							fallback: fallbackEnabled
-						}
-					})));
-					return EXIT_CODE.OK;
-				}
+				if (runtime.json) stdout(JSON.stringify(buildJsonSuccess({
+					command,
+					status: "ok",
+					repoRoot,
+					details: {
+						linked: commandArgs,
+						worktreePath: targetWorktreeRoot,
+						fallback: fallbackEnabled
+					}
+				})));
 				return EXIT_CODE.OK;
-			}
-			if (command === "lock") {
+			};
+			const handleLock = async () => {
 				ensureArgumentCount({
 					command,
 					args: commandArgs,
@@ -4535,25 +5570,22 @@ const createCli = (options = {}) => {
 						owner
 					});
 				});
-				if (runtime.json) {
-					stdout(JSON.stringify(buildJsonSuccess({
-						command,
-						status: "ok",
-						repoRoot,
-						details: {
-							branch,
-							locked: {
-								value: true,
-								reason: result.reason,
-								owner: result.owner
-							}
+				if (runtime.json) stdout(JSON.stringify(buildJsonSuccess({
+					command,
+					status: "ok",
+					repoRoot,
+					details: {
+						branch,
+						locked: {
+							value: true,
+							reason: result.reason,
+							owner: result.owner
 						}
-					})));
-					return EXIT_CODE.OK;
-				}
+					}
+				})));
 				return EXIT_CODE.OK;
-			}
-			if (command === "unlock") {
+			};
+			const handleUnlock = async () => {
 				ensureArgumentCount({
 					command,
 					args: commandArgs,
@@ -4598,24 +5630,21 @@ const createCli = (options = {}) => {
 						branch
 					});
 				});
-				if (runtime.json) {
-					stdout(JSON.stringify(buildJsonSuccess({
-						command,
-						status: "ok",
-						repoRoot,
-						details: {
-							branch,
-							locked: {
-								value: false,
-								reason: null
-							}
+				if (runtime.json) stdout(JSON.stringify(buildJsonSuccess({
+					command,
+					status: "ok",
+					repoRoot,
+					details: {
+						branch,
+						locked: {
+							value: false,
+							reason: null
 						}
-					})));
-					return EXIT_CODE.OK;
-				}
+					}
+				})));
 				return EXIT_CODE.OK;
-			}
-			if (command === "cd") {
+			};
+			const handleCd = async () => {
 				ensureArgumentCount({
 					command,
 					args: commandArgs,
@@ -4640,21 +5669,29 @@ const createCli = (options = {}) => {
 				}));
 				if (candidates.length === 0) throw createCliError("WORKTREE_NOT_FOUND", { message: "No worktree candidates found" });
 				const promptValue = readStringOption(parsedArgsRecord, "prompt");
+				const prompt = typeof promptValue === "string" && promptValue.length > 0 ? promptValue : resolvedConfig.selector.cd.prompt;
+				const cliFzfExtraArgs = collectOptionValues({
+					args: beforeDoubleDash,
+					optionNames: ["fzfArg", "fzf-arg"]
+				});
+				const mergedConfigFzfArgs = mergeFzfArgs({
+					defaults: resolvedConfig.selector.cd.fzf.extraArgs,
+					extras: cliFzfExtraArgs
+				});
+				const surface = resolvedConfig.selector.cd.surface;
 				const selection = await selectPathWithFzf$1({
 					candidates,
-					prompt: typeof promptValue === "string" && promptValue.length > 0 ? promptValue : "worktree> ",
+					prompt,
 					fzfExtraArgs: mergeFzfArgs({
 						defaults: CD_FZF_EXTRA_ARGS,
-						extras: collectOptionValues({
-							args: beforeDoubleDash,
-							optionNames: ["fzfArg", "fzf-arg"]
-						})
+						extras: mergedConfigFzfArgs
 					}),
+					surface,
+					tmuxPopupOpts: resolvedConfig.selector.cd.tmuxPopupOpts,
 					cwd: repoRoot,
 					isInteractive: () => runtime.isInteractive || process.stderr.isTTY === true
 				}).catch((error) => {
-					const message = error instanceof Error ? error.message : String(error);
-					if (message.includes("interactive terminal") || message.includes("fzf is required")) throw createCliError("DEPENDENCY_MISSING", { message: `DEPENDENCY_MISSING: ${message}` });
+					if (error instanceof FzfDependencyError || error instanceof FzfInteractiveRequiredError) throw createCliError("DEPENDENCY_MISSING", { message: `DEPENDENCY_MISSING: ${error.message}` });
 					throw error;
 				});
 				if (selection.status === "cancelled") return EXIT_CODE_CANCELLED;
@@ -4670,7 +5707,20 @@ const createCli = (options = {}) => {
 				}
 				stdout(selectedPath);
 				return EXIT_CODE.OK;
-			}
+			};
+			const miscCommandExitCode = await dispatchCommandHandler({
+				command,
+				handlers: createMiscCommandHandlers({
+					execHandler: handleExec,
+					invokeHandler: handleInvoke,
+					copyHandler: handleCopy,
+					linkHandler: handleLink,
+					lockHandler: handleLock,
+					unlockHandler: handleUnlock,
+					cdHandler: handleCd
+				})
+			});
+			if (miscCommandExitCode !== void 0) return miscCommandExitCode;
 			throw createCliError("UNKNOWN_COMMAND", { message: `Unknown command: ${command}` });
 		} catch (error) {
 			const cliError = ensureCliError(error);