vde-worktree 0.0.20 → 0.0.21

package/dist/index.mjs

@@ -750,22 +750,9 @@ const resolveExistingConfigFiles = async ({ cwd, repoRoot }) => {
 	}
 	return [...deduped.values()].sort((a, b) => a.order - b.order).map((entry) => entry.path);
 };
-const isPathInsideOrEqual$1 = ({ parentPath, childPath }) => {
-	const rel = relative(parentPath, childPath);
-	if (rel.length === 0) return true;
-	return rel !== ".." && rel.startsWith(`..${sep}`) !== true;
-};
 const validateWorktreeRoot = async ({ repoRoot, config }) => {
 	const rawWorktreeRoot = config.paths.worktreeRoot;
 	const resolvedWorktreeRoot = isAbsolute(rawWorktreeRoot) ? resolve(rawWorktreeRoot) : resolve(repoRoot, rawWorktreeRoot);
-	if (isPathInsideOrEqual$1({
-		parentPath: resolve(repoRoot, ".git"),
-		childPath: resolvedWorktreeRoot
-	})) throwInvalidConfig({
-		file: "<resolved>",
-		keyPath: "paths.worktreeRoot",
-		reason: "must not point inside .git"
-	});
 	try {
 		if ((await lstat(resolvedWorktreeRoot)).isDirectory() !== true) throwInvalidConfig({
 			file: "<resolved>",
@@ -989,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}`,
@@ -1002,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 {
@@ -1015,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.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) === 0) return;
-		const message = `Hook failed: ${hookName} (exitCode=${String(result.exitCode ?? 1)})`;
-		if (phase === "post" && context.strictPostHooks !== true) {
-			context.stderr(message);
+		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", {
@@ -1074,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", {
@@ -1204,6 +1257,79 @@ const initializeRepository = async ({ repoRoot, managedWorktreeRoot }) => {
 	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) => {
@@ -1221,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);
@@ -1259,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 {
@@ -1290,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 {
@@ -1339,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;
@@ -1424,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;
 };
@@ -1463,9 +1537,10 @@ const moveWorktreeMergeLifecycle = async ({ repoRoot, fromBranch, toBranch, base
 		createdAt: source.record?.createdAt ?? now,
 		updatedAt: now
 	};
-	await writeJsonAtomically$1({
+	await writeJsonAtomically({
 		filePath: targetPath,
-		payload: next
+		payload: next,
+		ensureDir: true
 	});
 	if (source.path !== targetPath) await rm(source.path, { force: true });
 	return next;
@@ -1476,58 +1551,18 @@ const deleteWorktreeMergeLifecycle = async ({ repoRoot, branch }) => {
 
 //#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
-		};
-	}
-};
-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 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({
@@ -1558,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();
@@ -1669,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
@@ -1677,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);
 	}
@@ -1743,6 +1806,9 @@ const listGitWorktrees = async (repoRoot) => {
 
 //#endregion
 //#region src/core/worktree-state.ts
+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({
 		cwd: worktreePath,
@@ -1750,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,
@@ -1767,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: [
@@ -1813,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",
@@ -1832,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 }) => {
@@ -1853,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,
@@ -2046,6 +2133,50 @@ const RESERVED_FZF_ARGS = new Set([
 ]);
 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, "");
@@ -2054,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 }) => {
@@ -2099,7 +2230,7 @@ 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;
@@ -2122,8 +2253,8 @@ const isTmuxUnknownOptionError = (error) => {
 	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 Error("No candidates provided for fzf selection");
-	if (isInteractive() !== true) throw new Error("fzf selection requires an interactive terminal");
+	if (candidates.length === 0) throw new FzfInvalidArgumentError("No candidates provided for fzf selection");
+	if (isInteractive() !== true) throw new FzfInteractiveRequiredError();
 	await ensureFzfAvailable(checkFzfAvailability);
 	const baseArgs = buildFzfArgs({
 		prompt,
@@ -2136,7 +2267,7 @@ const selectPathWithFzf = async ({ candidates, prompt = "worktree> ", surface =
 	});
 	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)));
 	const runWithValidation = async (fzfArgs) => {
 		const selectedPath = stripAnsi(stripTrailingNewlines((await runFzf({
@@ -2146,7 +2277,7 @@ const selectPathWithFzf = async ({ candidates, prompt = "worktree> ", surface =
 			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
@@ -2217,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"];
@@ -2584,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 {
@@ -2601,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) => {
@@ -2629,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];
@@ -2636,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) => {
@@ -3629,97 +3957,30 @@ 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);
@@ -3777,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,
@@ -3807,21 +4091,18 @@ const createCli = (options = {}) => {
 					});
 					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,
@@ -3893,8 +4174,8 @@ const createCli = (options = {}) => {
 				}) : 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,
@@ -3924,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,
@@ -3951,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,
@@ -3960,61 +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, resolvedConfig.paths.worktreeRoot);
-					await ensureTargetPathWritable(targetPath);
-					const baseBranch = await resolveBaseBranch({
-						repoRoot,
-						config: resolvedConfig
-					});
-					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({
@@ -4027,8 +4313,8 @@ const createCli = (options = {}) => {
 				}
 				stdout(result.path);
 				return EXIT_CODE.OK;
-			}
-			if (command === "switch") {
+			};
+			const handleSwitch = async () => {
 				ensureArgumentCount({
 					command,
 					args: commandArgs,
@@ -4053,62 +4339,57 @@ const createCli = (options = {}) => {
 						};
 					}
 					const targetPath = branchToWorktreePath(repoRoot, branch, resolvedConfig.paths.worktreeRoot);
-					await ensureTargetPathWritable(targetPath);
-					const hookContext = createHookContext({
-						runtime,
-						repoRoot,
-						action: "switch",
+					return executeWorktreeMutation({
+						name: "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,
-							config: resolvedConfig
-						});
-						lifecycleBaseBranch = baseBranch;
-						await runGitCommand({
-							cwd: repoRoot,
-							args: [
-								"worktree",
-								"add",
-								"-b",
+						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,
-								targetPath,
-								baseBranch
-							]
-						});
-					}
-					if (lifecycleBaseBranch !== null) await upsertWorktreeMergeLifecycle({
-						repoRoot,
-						branch,
-						baseBranch: lifecycleBaseBranch,
-						observedDivergedHead: null
-					});
-					await runPostHook({
-						name: "switch",
-						context: hookContext
+								path: targetPath
+							};
+						},
+						finalize: async ({ lifecycleBaseBranch }) => {
+							if (lifecycleBaseBranch !== null) await upsertWorktreeMergeLifecycle({
+								repoRoot,
+								branch,
+								baseBranch: lifecycleBaseBranch,
+								observedDivergedHead: null
+							});
+						}
 					});
-					return {
-						status: "created",
-						branch,
-						path: targetPath
-					};
 				});
 				if (runtime.json) {
 					stdout(JSON.stringify(buildJsonSuccess({
@@ -4124,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,
@@ -4152,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, resolvedConfig.paths.worktreeRoot);
-					await ensureTargetPathWritable(newPath);
-					const hookContext = createHookContext({
-						runtime,
-						repoRoot,
-						action: "mv",
+					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({
@@ -4226,8 +4515,8 @@ const createCli = (options = {}) => {
 				}
 				stdout(result.path);
 				return EXIT_CODE.OK;
-			}
-			if (command === "del") {
+			};
+			const handleDel = async () => {
 				ensureArgumentCount({
 					command,
 					args: commandArgs,
@@ -4268,56 +4557,58 @@ const createCli = (options = {}) => {
 							managedWorktreeRoot
 						}
 					});
-					validateDeleteSafety({
-						target,
-						forceFlags
-					});
-					const hookContext = createHookContext({
-						runtime,
-						repoRoot,
-						action: "del",
-						branch: target.branch,
-						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
-					});
-					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({
@@ -4330,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,
@@ -4421,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,
@@ -4541,8 +4840,8 @@ const createCli = (options = {}) => {
 				}
 				stdout(result.path);
 				return EXIT_CODE.OK;
-			}
-			if (command === "extract") {
+			};
+			const handleExtract = async () => {
 				ensureArgumentCount({
 					command,
 					args: commandArgs,
@@ -4674,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,
@@ -4797,8 +5105,8 @@ const createCli = (options = {}) => {
 				}
 				stdout(result.path);
 				return EXIT_CODE.OK;
-			}
-			if (command === "unabsorb") {
+			};
+			const handleUnabsorb = async () => {
 				ensureArgumentCount({
 					command,
 					args: commandArgs,
@@ -4930,8 +5238,8 @@ const createCli = (options = {}) => {
 				}
 				stdout(result.path);
 				return EXIT_CODE.OK;
-			}
-			if (command === "use") {
+			};
+			const handleUse = async () => {
 				ensureArgumentCount({
 					command,
 					args: commandArgs,
@@ -5024,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,
@@ -5080,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,
@@ -5105,21 +5422,18 @@ 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,
@@ -5145,21 +5459,18 @@ const createCli = (options = {}) => {
 						dereference: false
 					});
 				}
-				if (runtime.json) {
-					stdout(JSON.stringify(buildJsonSuccess({
-						command,
-						status: "ok",
-						repoRoot,
-						details: {
-							copied: commandArgs,
-							worktreePath: targetWorktreeRoot
-						}
-					})));
-					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,
@@ -5205,22 +5516,19 @@ const createCli = (options = {}) => {
 						});
 					}
 				}
-				if (runtime.json) {
-					stdout(JSON.stringify(buildJsonSuccess({
-						command,
-						status: "ok",
-						repoRoot,
-						details: {
-							linked: commandArgs,
-							worktreePath: targetWorktreeRoot,
-							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,
@@ -5262,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,
@@ -5325,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,
@@ -5389,8 +5691,7 @@ const createCli = (options = {}) => {
 					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;
@@ -5406,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);