stim 1.0.0 → 1.2.0

package/dist/worktree-BPTbI-LN.mjs

@@ -0,0 +1,1322 @@
+import { t as getExecutor } from "./exec-CyylIdq9.mjs";
+import { S as upsertProject, f as getProject, g as loadConfig, h as isPathPrefix, u as getConfigDir, v as removeProject, w as captureProcessIdentity } from "./config-CMtIaTk9.mjs";
+import { c as readMetroTunnel, u as readRemoteSession } from "./state-CZ-ER-8d.mjs";
+import { _ as resolveFullRef, b as warmWorktreePaths, c as hasRemote, d as isPodInstallChurn, f as listWorktrees, h as removeWorktree, i as depsOutOfSync, l as hasUncommittedWork, m as readWorktreeExclude, n as cloneIgnoredEntries, o as dirtyPaths, p as podsOutOfSync, r as deleteBranch, s as gitCommonDir, t as branchExists, u as isMainWorkingTree, v as restoreFile, y as unpushedCommits } from "./worktree-C79xx_kM.mjs";
+import { a as findProjectRoot } from "./project-BBTVABUz.mjs";
+import { v as POOL_SETTING_REMEDY, x as parkedMaxSetting } from "./remote-cache-DDmJ1Roq.mjs";
+import { A as resolveSettings, I as unknownSettingKeys, N as settingShapeErrors, a as SETTING_SHAPE_REMEDY } from "./settings-DwU1_U_q.mjs";
+import { a as formatElapsed, f as releasedLeaseFact, i as formatDuration, l as phaseLine, m as shortUdid, u as plural } from "./command-output-8wHMEde0.mjs";
+import { a as clearClaimChild, c as isClaimUnavailable, d as readClaimSet, f as releaseClaim, h as tryAcquireClaim, i as claimRemoveCommand, l as markClaimChildPending, m as settleClaim, p as setClaimChild, r as claimFailure, s as isClaimRefusal, u as processGroupAlive } from "./ownership-claim-7zRxxTfZ.mjs";
+import { g as podInstallCommand, r as HEARTBEAT_INTERVAL_MS } from "./xcode-DeKCribl.mjs";
+import { a as installedNpmTreeIsValid, i as hasInstalledDependencies, o as locallyKnownUpstream, t as dependencyState } from "./doctor-CqPeMsSm.mjs";
+import { c as withManagedTunnelRemovalLock, o as withManagedRemoteWorktreeRemovalLock } from "./ownership-CYOyqxUo.mjs";
+import { n as reclaimProject } from "./reclaim-C5Jmuahx.mjs";
+import { a as runPodInstall, i as runCaptured, n as podsAreStale, r as readPodState, t as DEPS_ERROR } from "./deps-BLBsTNDS.mjs";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { join, relative } from "node:path";
+import { existsSync as existsSync$1, realpathSync as realpathSync$1 } from "fs";
+import { basename as basename$1, dirname as dirname$1, isAbsolute as isAbsolute$1, relative as relative$1, resolve as resolve$1 } from "path";
+import { workspaceName } from "@stim-cli/core";
+import chalk from "chalk";
+//#region src/engine/warm-claim.ts
+const WARM_CLAIM_LABEL = "worktree warm";
+const WARM_CLAIM_POLL_MS = 250;
+const WARM_CLAIM_PROGRESS_MS = 3e4;
+const WARM_CLAIM_CEILING_MS = 54e5;
+const INSTALLER_POLL_MS = 50;
+const INSTALLER_CEILING_MS = 3e5;
+const NO_INSTALLER_CLAIM = {
+	declare: () => {},
+	record: () => {},
+	settle: async () => ({
+		settled: true,
+		pid: null,
+		waitedMs: 0
+	})
+};
+function defaultSleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function warmClaimsDir() {
+	return join(getConfigDir(), "warm-locks");
+}
+function warmClaimPath(repositoryRoot) {
+	return join(warmClaimsDir(), `${workspaceName(repositoryRoot)}.lock`);
+}
+function warmCommand(phase) {
+	return phase === "refresh" ? "stim worktree warm --refresh" : "stim worktree warm";
+}
+function asHolder(holder) {
+	return {
+		pid: holder.owner.pid,
+		phase: holder.mode === "exclusive" ? "refresh" : "copy"
+	};
+}
+function waitingLine(holder, elapsedMs) {
+	return phaseLine("lock", `waiting ${formatElapsed(elapsedMs)} for ${warmCommand(holder.phase)} (pid ${holder.pid}) -- stim guide lifecycle options`);
+}
+function warmClaimAcquiredLine(wait) {
+	if (!wait.holder || wait.waitedMs <= 0) return phaseLine("lock", "acquired");
+	return phaseLine("lock", `acquired (waited ${formatElapsed(wait.waitedMs)} for ${warmCommand(wait.holder.phase)} pid ${wait.holder.pid}) -- stim guide lifecycle options`);
+}
+function warmClaimUnavailableLine(reason) {
+	return phaseLine("lock", `unavailable (${reason}); copying without it`);
+}
+/**
+* The reason a copy may proceed without the claim, or null when it must refuse. Plain `warm` worked on an
+* unwritable STIM_HOME before any claim existed and only reads, so the states in which no claim can be
+* recorded at all degrade to an unsynchronised copy: no process identity, a claim store the filesystem
+* rejects, and a claim store whose own path holds a file. A claim record Stim cannot resolve and a wait
+* that ran out are refusals: neither state can exist unless the claim does, so refusing them takes
+* nothing away.
+*/
+function warmClaimDegradation(error) {
+	if (isClaimUnavailable(error)) return error.message;
+	if (isClaimRefusal(error)) return error.reason === "the claim path is a file, not a claim directory" ? `${error.claimPath}: ${error.reason}` : null;
+	const code = error?.code;
+	if (typeof code === "string" && code.startsWith("STIM_")) return null;
+	return error?.message ?? String(error);
+}
+/**
+* What a copy that could not record a claim of its own would overlap if it went ahead anyway. Reading the
+* claim set classifies without writing anything and without refusing, so it works in exactly the states
+* that made the claim unrecordable -- a read-only STIM_HOME included. It is a read before a copy rather
+* than a held claim, so a refresh that starts after it is not covered; it closes the window in which one
+* is already installing, which is the window a refresh actually occupies.
+*/
+function warmClaimBlocker(repositoryRoot) {
+	const survey = readClaimSet(warmClaimPath(repositoryRoot));
+	const refresh = survey.live.find((holder) => holder.mode === "exclusive");
+	if (refresh) return {
+		kind: "refresh",
+		holder: asHolder(refresh)
+	};
+	const unresolved = survey.unresolved.find((problem) => problem.path.endsWith(".claim"));
+	if (unresolved) return {
+		kind: "unresolved",
+		path: unresolved.path,
+		reason: unresolved.reason
+	};
+	return null;
+}
+function warmClaimBlockedLine(reason, blocker) {
+	const what = blocker.kind === "refresh" ? `${warmCommand(blocker.holder.phase)} (pid ${blocker.holder.pid}) holds this repository` : `a claim at ${blocker.path} cannot be resolved: ${blocker.reason}`;
+	return phaseLine("lock", `unavailable (${reason}); ${what}`);
+}
+function warmClaimBlockedRefusal(blocker) {
+	if (blocker.kind === "refresh") return "Refusing to copy from a source checkout a refresh is rewriting, even without a claim of its own. Wait for that refresh to finish, then run warm again.";
+	return `Refusing to copy past a claim Stim cannot resolve. If nothing is warming, remove it and run warm again:\n  ${claimRemoveCommand(blocker.path)}`;
+}
+function installerWaitingLine(pid, elapsedMs) {
+	return phaseLine("lock", `waiting on the install this refresh spawned (pid ${pid}, ${formatElapsed(elapsedMs)} elapsed) -- stim guide lifecycle options`);
+}
+function installerUnrecordedLine(reason) {
+	return phaseLine("lock", `could not record the install this refresh spawned (${reason}); holding the claim here until it exits`);
+}
+function installerClaim(claim, { now, progressMs, out }) {
+	let groups = [];
+	const forget = () => {
+		groups = [];
+		try {
+			clearClaimChild(claim);
+		} catch {}
+	};
+	const alive = () => groups.find((pid) => processGroupAlive(pid)) ?? null;
+	return {
+		declare: () => markClaimChildPending(claim),
+		record: (pid) => {
+			if (pid === null) {
+				forget();
+				return;
+			}
+			groups.push(pid);
+			const captured = captureProcessIdentity(pid);
+			let failure = captured.ok ? null : captured.reason;
+			if (captured.ok) try {
+				setClaimChild(claim, {
+					pid,
+					processToken: captured.token
+				});
+				return;
+			} catch (error) {
+				failure = error?.message ?? String(error);
+			}
+			if (!processGroupAlive(pid)) {
+				forget();
+				return;
+			}
+			out(installerUnrecordedLine(String(failure)));
+		},
+		settle: async () => {
+			const started = now();
+			let lastProgress = started;
+			for (;;) {
+				const pid = alive();
+				if (pid === null) {
+					forget();
+					return {
+						settled: true,
+						pid: null,
+						waitedMs: now() - started
+					};
+				}
+				const elapsed = now() - started;
+				if (elapsed >= INSTALLER_CEILING_MS) return {
+					settled: false,
+					pid,
+					waitedMs: elapsed
+				};
+				if (now() - lastProgress >= progressMs) {
+					lastProgress = now();
+					out(installerWaitingLine(pid, elapsed));
+				}
+				await defaultSleep(INSTALLER_POLL_MS);
+			}
+		},
+		holding: () => alive() !== null
+	};
+}
+function timeoutError(holder, elapsedMs, root) {
+	const who = holder ? `${warmCommand(holder.phase)} (pid ${holder.pid})` : "another stim worktree warm";
+	const error = /* @__PURE__ */ new Error(`Waited ${formatElapsed(elapsedMs)} for ${who} to release the warm lock on this repository. The lock is ${root}; remove it if nothing is really warming:\n  ${claimRemoveCommand(root)}`);
+	error.code = "STIM_LOCK_TIMEOUT";
+	return error;
+}
+async function acquireWarmClaim({ repositoryRoot, phase, now = Date.now, sleep = defaultSleep, pollMs = WARM_CLAIM_POLL_MS, progressMs = WARM_CLAIM_PROGRESS_MS, ceilingMs = WARM_CLAIM_CEILING_MS, out = () => {} }) {
+	const root = warmClaimPath(repositoryRoot);
+	const started = now();
+	let lastProgress = started;
+	let waitedOn = null;
+	let pending = null;
+	try {
+		for (;;) {
+			const attempt = pending ? settleClaim(pending) : tryAcquireClaim({
+				root,
+				mode: phase === "refresh" ? "exclusive" : "shared",
+				label: WARM_CLAIM_LABEL
+			});
+			const acquired = attempt.acquired;
+			if (acquired) {
+				const installer = installerClaim(acquired, {
+					now,
+					progressMs,
+					out
+				});
+				return {
+					wait: {
+						waitedMs: now() - started,
+						holder: waitedOn
+					},
+					installer,
+					release: () => {
+						if (installer.holding()) return;
+						releaseClaim(acquired);
+					}
+				};
+			}
+			pending = attempt.pending ?? null;
+			const holder = attempt.held ?? attempt.waitingFor?.[0];
+			if (holder) waitedOn = asHolder(holder);
+			const elapsed = now() - started;
+			if (elapsed >= ceilingMs) throw timeoutError(waitedOn, elapsed, root);
+			if (waitedOn && now() - lastProgress >= progressMs) {
+				lastProgress = now();
+				out(waitingLine(waitedOn, elapsed));
+			}
+			await sleep(pollMs);
+		}
+	} catch (error) {
+		releaseClaim(pending);
+		throw error;
+	}
+}
+async function withWarmClaim(options, fn) {
+	const { release, ...hold } = await acquireWarmClaim(options);
+	try {
+		return await fn(hold);
+	} finally {
+		release();
+	}
+}
+//#endregion
+//#region src/worktree-refresh.ts
+const DIRTY_PATHS_SHOWN = 5;
+const FETCH_TIMEOUT_MS = 12e4;
+function mainCheckoutRefusal(root, state) {
+	if (state.operation) return {
+		code: "STIM_MAIN_DIRTY",
+		message: `Refusing to refresh ${root}: a ${state.operation === "am" ? "git am" : state.operation} is in progress there.`,
+		lines: [],
+		remedy: `Finish it, or run \`git -C ${root} ${state.operation} --abort\`, then run warm again.`
+	};
+	if (!state.dirtyKnown) return {
+		code: "STIM_MAIN_DIRTY",
+		message: `Refusing to refresh ${root}: git could not report whether its tracked files are modified.`,
+		lines: [],
+		remedy: `Run \`git -C ${root} status\` to see what it reports, clear it, then run warm again.`
+	};
+	if (state.dirtyTracked.length) return {
+		code: "STIM_MAIN_DIRTY",
+		message: `Refusing to refresh ${root}: it has uncommitted changes to tracked files.`,
+		lines: state.dirtyTracked.slice(0, DIRTY_PATHS_SHOWN),
+		remedy: `Commit them, or run \`git -C ${root} stash push -u -m warm-refresh\`, then run warm again.`
+	};
+	if (state.branch === null) return {
+		code: "STIM_MAIN_DETACHED",
+		message: `Refusing to refresh ${root}: its HEAD is detached, so there is no branch to fast-forward.`,
+		lines: [],
+		remedy: `Run \`git -C ${root} checkout <branch>\`, then run warm again.`
+	};
+	return null;
+}
+function checkoutPlan(upstream) {
+	if (!upstream) return { kind: "no-upstream" };
+	const { name, ahead, behind } = upstream;
+	if (ahead > 0 && behind > 0) return {
+		kind: "diverged",
+		ahead,
+		behind,
+		upstream: name
+	};
+	if (behind > 0) return {
+		kind: "fast-forward",
+		behind,
+		upstream: name
+	};
+	return {
+		kind: "current",
+		ahead,
+		upstream: name
+	};
+}
+function divergedRefusal(root, branch, plan) {
+	return {
+		code: "STIM_MAIN_DIVERGED",
+		message: `Refusing to refresh ${root}: ${branch} is ${plan.ahead} ahead of and ${plan.behind} behind ${plan.upstream}, so it cannot fast-forward.`,
+		lines: [],
+		remedy: `Rebase or merge ${branch} yourself, then run warm again. Warm never merges, resets, or switches a branch.`
+	};
+}
+function checkoutFactLine(branch, plan, head) {
+	const shortHead = head.slice(0, 7);
+	if (plan.kind === "no-upstream") return phaseLine("checkout", `${branch} has no upstream -> left${shortHead ? ` at ${shortHead}` : " alone"}`);
+	if (plan.kind === "fast-forward") return phaseLine("checkout", `${branch} ${plan.behind} commit${plan.behind === 1 ? "" : "s"} behind ${plan.upstream} -> fast-forwarded to ${shortHead}`);
+	const ahead = plan.ahead > 0 ? `, ${plan.ahead} ahead` : "";
+	return phaseLine("checkout", `${branch} up to date with ${plan.upstream}${ahead}`);
+}
+/**
+* Whether to install, decided against the lockfile as it stands now rather than against what HEAD did.
+* A lockfile that did not move is not evidence that its dependencies are installed: an install that was
+* interrupted leaves a present node_modules behind and moves HEAD no further.
+*/
+function depsPlan({ lockfile, lockfileChanged, installed, treeValid, lastInstall, lockHash }) {
+	if (!lockfile) return {
+		run: false,
+		reason: "no lockfile in this repository"
+	};
+	if (!installed) return {
+		run: true,
+		reason: "no installed dependencies"
+	};
+	if (treeValid === false) return {
+		run: true,
+		reason: `the installed tree does not match ${lockfile}`
+	};
+	if (lastInstall) {
+		if (!lastInstall.completed) return {
+			run: true,
+			reason: `the last install of ${lastInstall.lock} did not finish`
+		};
+		if (lastInstall.lock !== lockfile) return {
+			run: true,
+			reason: `the last completed install was of ${lastInstall.lock}`
+		};
+		if (lockHash === null || lastInstall.hash !== lockHash) return {
+			run: true,
+			reason: `${lockfile} does not match the last completed install`
+		};
+		return {
+			run: false,
+			reason: `${lockfile} matches the last completed install`
+		};
+	}
+	if (lockfileChanged) return {
+		run: true,
+		reason: `${lockfile} changed`
+	};
+	return {
+		run: false,
+		reason: `${lockfile} unchanged`
+	};
+}
+/**
+* Why a copy must not read the source checkout's dependencies: the install recorded for the lockfile as it
+* stands now did not finish, so what is installed there is partial. A record of any other lockfile says
+* nothing about this one, and no record at all is the state of every repository before its first refresh.
+*/
+function incompleteInstallRefusal(root, appDir) {
+	const dependencies = dependencyState(existsSync(appDir) ? appDir : root);
+	if (!dependencies) return null;
+	const last = readInstallEvidence(dependencies.root);
+	if (!last || last.completed || last.lock !== dependencies.lock) return null;
+	const hash = lockfileHash(dependencies.root, dependencies.lock);
+	if (hash === null || last.hash !== hash) return null;
+	return {
+		code: "STIM_DEPS_INCOMPLETE",
+		message: `Refusing to copy from ${dependencies.root}: the last install of ${dependencies.lock} there did not finish, so its dependencies are partial.`,
+		lines: [],
+		remedy: `Run \`stim worktree warm --refresh\` to install them in the source checkout -- it reinstalls rather than skipping, because no completed install of this ${dependencies.lock} is recorded -- then warm again.`
+	};
+}
+function podsPlan({ hasIos, hasPodfile, podfileLockChanged, stale }) {
+	if (!hasIos) return {
+		run: false,
+		reason: "no ios/ directory"
+	};
+	if (!hasPodfile) return {
+		run: false,
+		reason: "no ios/Podfile"
+	};
+	if (stale.noPods) return {
+		run: false,
+		reason: "no ios/Pods and no ios/Podfile.lock"
+	};
+	if (podfileLockChanged) return {
+		run: true,
+		reason: "ios/Podfile.lock changed"
+	};
+	if (stale.stale) return {
+		run: true,
+		reason: stale.reason ?? "ios/Pods does not match ios/Podfile.lock"
+	};
+	return {
+		run: false,
+		reason: "ios/Podfile.lock unchanged"
+	};
+}
+function defaultBranchNote(branch, defaultBranch) {
+	if (defaultBranch === null) return {
+		kind: "unknown",
+		lines: ["could not tell the default branch: no worktree.defaultBranch setting and no", "origin/HEAD. Run `git remote set-head origin -a` to record one."]
+	};
+	if (defaultBranch === branch) return { kind: "match" };
+	return {
+		kind: "warn",
+		lines: [`not the default branch (${defaultBranch}); worktrees seeded from this copy`, `carry ${branch}'s dependencies`]
+	};
+}
+function stepLine(label, reason, action) {
+	return phaseLine(label, `${reason} -> ${action}`);
+}
+function installRecordFile(depsRoot) {
+	return join(getConfigDir(), "warm-installs", `${workspaceName(depsRoot)}.json`);
+}
+function lockfileHash(depsRoot, lockfile) {
+	try {
+		return createHash("sha256").update(readFileSync(join(depsRoot, lockfile))).digest("hex");
+	} catch {
+		return null;
+	}
+}
+function readInstallEvidence(depsRoot) {
+	try {
+		const parsed = JSON.parse(readFileSync(installRecordFile(depsRoot), "utf-8"));
+		if (!parsed || typeof parsed !== "object") return null;
+		if (typeof parsed.lock !== "string" || typeof parsed.hash !== "string") return null;
+		return {
+			lock: parsed.lock,
+			hash: parsed.hash,
+			completed: parsed.completed === true
+		};
+	} catch {
+		return null;
+	}
+}
+function writeInstallEvidence(depsRoot, lockfile, hash, completed) {
+	const file = installRecordFile(depsRoot);
+	const tmp = `${file}.${process.pid}.${randomUUID()}.tmp`;
+	mkdirSync(join(getConfigDir(), "warm-installs"), { recursive: true });
+	writeFileSync(tmp, JSON.stringify({
+		lock: lockfile,
+		hash: hash ?? "",
+		completed
+	}));
+	try {
+		renameSync(tmp, file);
+	} catch (error) {
+		rmSync(tmp, { force: true });
+		throw error;
+	}
+}
+function restoreInstallEvidence(depsRoot, prior) {
+	if (prior) writeInstallEvidence(depsRoot, prior.lock, prior.hash, prior.completed);
+	else rmSync(installRecordFile(depsRoot), { force: true });
+}
+function inProgressOperation(gitDir) {
+	if (existsSync(join(gitDir, "rebase-merge"))) return "rebase";
+	if (existsSync(join(gitDir, "rebase-apply"))) return existsSync(join(gitDir, "rebase-apply", "applying")) ? "am" : "rebase";
+	return existsSync(join(gitDir, "MERGE_HEAD")) ? "merge" : null;
+}
+function readMainCheckoutState(root) {
+	const exec = getExecutor();
+	const gitDir = exec.runFileQuiet("git", [
+		"-C",
+		root,
+		"rev-parse",
+		"--path-format=absolute",
+		"--git-dir"
+	])?.trim();
+	const worktreeChanged = exec.runFileQuiet("git", [
+		"-C",
+		root,
+		"diff",
+		"--name-only",
+		"HEAD"
+	]);
+	const indexChanged = exec.runFileQuiet("git", [
+		"-C",
+		root,
+		"diff",
+		"--name-only",
+		"--cached",
+		"HEAD"
+	]);
+	const branch = exec.runFileQuiet("git", [
+		"-C",
+		root,
+		"symbolic-ref",
+		"--quiet",
+		"--short",
+		"HEAD"
+	])?.trim() || null;
+	const paths = [worktreeChanged, indexChanged].flatMap((out) => (out ?? "").split("\n").map((line) => line.trim()).filter(Boolean));
+	return {
+		branch,
+		operation: gitDir ? inProgressOperation(gitDir) : null,
+		dirtyTracked: [...new Set(paths)],
+		dirtyKnown: worktreeChanged !== null && indexChanged !== null
+	};
+}
+function resolveDefaultBranch(root, settings) {
+	const worktree = settings.worktree;
+	const configured = worktree && typeof worktree === "object" && !Array.isArray(worktree) ? worktree.defaultBranch : void 0;
+	if (typeof configured === "string" && configured.trim()) return configured.trim();
+	const head = getExecutor().runFileQuiet("git", [
+		"-C",
+		root,
+		"symbolic-ref",
+		"--short",
+		"refs/remotes/origin/HEAD"
+	])?.trim();
+	if (!head) return null;
+	const cut = head.indexOf("/");
+	return cut > 0 ? head.slice(cut + 1) : head;
+}
+function branchRemote(root, branch) {
+	return getExecutor().runFileQuiet("git", [
+		"-C",
+		root,
+		"config",
+		`branch.${branch}.remote`
+	])?.trim() || "origin";
+}
+function gitPath(...parts) {
+	return parts.filter((part) => part && part !== ".").join("/");
+}
+function pathChangedBetween(root, from, to, path) {
+	if (from === to || !from || !to) return false;
+	const out = getExecutor().runFileQuiet("git", [
+		"-C",
+		root,
+		"diff",
+		"--name-only",
+		from,
+		to,
+		"--",
+		path
+	]);
+	return Boolean(out && out.trim());
+}
+async function runInstallCommand({ command, cwd, spawnFn, now, heartbeatMs, onHeartbeat }) {
+	const [bin, ...args] = command.split(" ");
+	const run = await runCaptured({
+		logWriter: null,
+		spawn: spawnFn,
+		now,
+		heartbeatMs,
+		onHeartbeat,
+		cmd: String(bin),
+		args,
+		cwd,
+		env: {
+			...process.env,
+			FORCE_COLOR: "0"
+		},
+		event: "warm_deps_install",
+		label: "deps"
+	});
+	const lastLines = run.transcript.slice(-20);
+	if (run.error) {
+		const reason = `Could not run \`${command}\`: ${run.error?.message || run.error}`;
+		return {
+			ok: false,
+			durationMs: run.durationMs,
+			reason,
+			lastLines
+		};
+	}
+	if (run.code !== 0) {
+		const how = run.signal ? `signal ${run.signal}` : `exit code ${run.code}`;
+		return {
+			ok: false,
+			durationMs: run.durationMs,
+			reason: `\`${command}\` failed (${how}).`,
+			lastLines
+		};
+	}
+	return {
+		ok: true,
+		durationMs: run.durationMs,
+		reason: null,
+		lastLines
+	};
+}
+function fastForward(root, upstream) {
+	try {
+		getExecutor().runFile("git", [
+			"-C",
+			root,
+			"merge",
+			"--ff-only",
+			"--end-of-options",
+			upstream
+		]);
+		return {
+			ok: true,
+			lines: []
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			lines: String(error?.stderr || error?.message || error).split("\n").map((line) => line.trim()).filter(Boolean).slice(0, 5)
+		};
+	}
+}
+async function refreshMainCheckout({ root, appDir, settings, emit, spawnFn = null, now = Date.now, heartbeatMs = HEARTBEAT_INTERVAL_MS, installer = NO_INSTALLER_CLAIM }) {
+	const state = readMainCheckoutState(root);
+	const refusal = mainCheckoutRefusal(root, state);
+	if (refusal) return refusal;
+	const branch = String(state.branch);
+	const spawnChild = spawnFn || ((cmd, args, opts) => getExecutor().spawn(cmd, args, opts));
+	const spawn = (cmd, args, opts) => {
+		installer.declare();
+		let child;
+		try {
+			child = spawnChild(cmd, args, {
+				...opts,
+				detached: true
+			});
+		} catch (error) {
+			installer.record(null);
+			throw error;
+		}
+		installer.record(child.pid ?? null);
+		return child;
+	};
+	/**
+	* A package manager's own exit does not mean its install is over: `npm ci` spawns postinstall writers
+	* that outlive it, and one of those rewriting node_modules is exactly what the claim exists to keep a
+	* copy away from. So the group, not the direct child, decides when the install is done.
+	*/
+	const awaitSpawnedWork = async (what) => {
+		const settled = await installer.settle();
+		if (settled.settled) return null;
+		return {
+			code: DEPS_ERROR,
+			message: `${what} exited but left a process group running (pid ${settled.pid}) in ${root} after ${formatElapsed(settled.waitedMs)}, so Stim cannot tell that it finished writing.`,
+			lines: [],
+			remedy: `Stop what pid ${settled.pid} leads (\`ps -g ${settled.pid}\`, then \`kill -TERM -${settled.pid}\`) and run warm again. The warm claim stays held until that group exits, so no copy reads a half-written tree in the meantime.`
+		};
+	};
+	const before = resolveFullRef(root, "HEAD") ?? "";
+	if (getExecutor().runFileQuiet("git", [
+		"-C",
+		root,
+		"fetch",
+		"--prune",
+		branchRemote(root, branch)
+	], {
+		timeoutMs: FETCH_TIMEOUT_MS,
+		env: { GIT_TERMINAL_PROMPT: "0" }
+	}) === null) emit(phaseLine("checkout", "could not fetch; continuing with the local state"));
+	const plan = checkoutPlan(locallyKnownUpstream(root));
+	if (plan.kind === "diverged") return divergedRefusal(root, branch, plan);
+	const depsBefore = dependencyState(existsSync(appDir) ? appDir : root);
+	const priorInstall = depsBefore ? readInstallEvidence(depsBefore.root) : null;
+	const marked = plan.kind === "fast-forward" ? depsBefore : null;
+	if (marked) writeInstallEvidence(marked.root, marked.lock, lockfileHash(marked.root, marked.lock), false);
+	let head = before;
+	if (plan.kind === "fast-forward") {
+		const merged = fastForward(root, plan.upstream);
+		if (!merged.ok) return {
+			code: "STIM_MAIN_DIRTY",
+			message: `Refusing to refresh ${root}: git could not fast-forward ${branch} to ${plan.upstream}.`,
+			lines: merged.lines,
+			remedy: "Clear what git reports in the source checkout, then run warm again."
+		};
+		head = resolveFullRef(root, "HEAD") ?? before;
+	}
+	emit(checkoutFactLine(branch, plan, head));
+	const note = defaultBranchNote(branch, resolveDefaultBranch(root, settings));
+	if (note.kind !== "match") for (const line of note.lines) emit(phaseLine("", line));
+	const dependencies = dependencyState(existsSync(appDir) ? appDir : root);
+	const installed = dependencies ? hasInstalledDependencies(dependencies.root, dependencies.installed) : false;
+	const consumed = dependencies ? lockfileHash(dependencies.root, dependencies.lock) : null;
+	const deps = depsPlan({
+		lockfile: dependencies?.lock ?? null,
+		lockfileChanged: dependencies ? pathChangedBetween(root, before, head, gitPath(relative(root, dependencies.root), dependencies.lock)) : false,
+		installed,
+		treeValid: dependencies?.lock === "package-lock.json" && installed ? installedNpmTreeIsValid(dependencies.root) : null,
+		lastInstall: priorInstall,
+		lockHash: consumed
+	});
+	const depsSubject = `source ${dependencies?.root ?? root}: ${deps.reason}`;
+	if (deps.run && dependencies) {
+		writeInstallEvidence(dependencies.root, dependencies.lock, consumed, false);
+		const install = await runInstallCommand({
+			command: dependencies.command,
+			cwd: dependencies.root,
+			spawnFn: spawn,
+			now,
+			heartbeatMs,
+			onHeartbeat: emit
+		});
+		emit(stepLine("deps", depsSubject, `${dependencies.command} (${formatDuration(install.durationMs)})`));
+		const running = await awaitSpawnedWork(`\`${dependencies.command}\``);
+		if (!install.ok) return {
+			code: DEPS_ERROR,
+			message: String(install.reason),
+			lines: install.lastLines,
+			remedy: `Run \`cd ${dependencies.root} && ${dependencies.command}\` and fix what it reports, then run warm again.`
+		};
+		if (running) return running;
+		writeInstallEvidence(dependencies.root, dependencies.lock, consumed, true);
+	} else {
+		if (marked) restoreInstallEvidence(marked.root, priorInstall);
+		emit(stepLine("deps", depsSubject, "skipped"));
+	}
+	const app = relative(root, appDir) || ".";
+	const where = `source ${appDir}: `;
+	const podState = readPodState(appDir);
+	const pods = podsPlan({
+		hasIos: existsSync(join(appDir, "ios")),
+		hasPodfile: podState.hasPodfile,
+		podfileLockChanged: pathChangedBetween(root, before, head, gitPath(app, "ios", "Podfile.lock")),
+		stale: podsAreStale(podState.lockText, podState.manifestText)
+	});
+	if (!pods.run) {
+		emit(stepLine("pods", `${where}${pods.reason}`, "skipped"));
+		return null;
+	}
+	const result = await runPodInstall(appDir, null, {
+		spawnFn: spawn,
+		now,
+		heartbeatMs,
+		onHeartbeat: emit
+	});
+	const podCommand = result.command ?? "pod install";
+	emit(stepLine("pods", `${where}${pods.reason}`, result.durationMs === void 0 ? podCommand : `${podCommand} (${formatDuration(result.durationMs)})`));
+	for (const podNote of result.notes ?? []) emit(phaseLine("pods", podNote));
+	const podsRunning = await awaitSpawnedWork(`\`${podCommand}\``);
+	if (!result.ok) return {
+		code: result.code ?? "STIM_DEPS_FAILED",
+		message: result.reason ?? "`pod install` failed.",
+		lines: result.lastLines ?? [],
+		remedy: result.remedy ?? null
+	};
+	return podsRunning;
+}
+//#endregion
+//#region src/commands/worktree.ts
+function dependencyInstallCommand(target, dir = ".") {
+	const installRoot = resolve$1(target, dir);
+	let command = "npm install";
+	if (existsSync$1(resolve$1(installRoot, "pnpm-lock.yaml"))) command = "pnpm install";
+	else if (existsSync$1(resolve$1(installRoot, "yarn.lock"))) command = "yarn install";
+	else if (existsSync$1(resolve$1(installRoot, "bun.lock")) || existsSync$1(resolve$1(installRoot, "bun.lockb"))) command = "bun install";
+	else if (existsSync$1(resolve$1(installRoot, "package-lock.json"))) command = "npm ci";
+	return `cd '${installRoot.replaceAll("'", "'\\''")}' && ${command}`;
+}
+function reportCarriedStateHealth(root, target, copied) {
+	const staleDeps = depsOutOfSync(root, target, copied);
+	if (staleDeps.length) {
+		const manifests = staleDeps.map((d) => d.dir === "." ? d.lockfile : `${d.dir}/${d.lockfile}`).join(", ");
+		const remedies = [...new Set(staleDeps.map((dependency) => dependencyInstallCommand(target, dependency.dir)))];
+		console.error(chalk.yellow(phaseLine("carry", `carried dependencies may be stale: they do not match ${manifests}. Run ${remedies.map((command) => `\`${command}\``).join(" and ")} before building.`)));
+	}
+	for (const p of podsOutOfSync(target, copied)) {
+		const where = p.dir === "." ? "Podfile.lock" : `${p.dir}/Podfile.lock`;
+		const pod = podInstallCommand(p.dir === "." ? target : resolve$1(target, p.dir, ".."));
+		console.error(chalk.yellow(phaseLine("carry", p.reason === "missing" ? `carried ${p.dir === "." ? "Pods" : `${p.dir}/Pods`} but there is no ${where}. Run \`${pod}\` before building.` : `carried ${p.dir === "." ? "Pods" : `${p.dir}/Pods`} does not match the ${where} on disk here. Pods are gitignored and cloned; Podfile.lock is tracked, so the two can disagree. Run \`${pod}\` before building, or xcodebuild fails with "sandbox is not in sync" only after every pod has compiled.`)));
+	}
+}
+function reportRefreshFailure(failure) {
+	console.error(chalk.red(failure.message));
+	for (const line of failure.lines) console.error(chalk.dim(`  ${line}`));
+	if (failure.remedy) console.error(chalk.dim(failure.remedy));
+	console.error(chalk.red(`failed: ${failure.code}`));
+	process.exitCode = 1;
+}
+function mainCheckoutAppDir(root, target) {
+	const app = findProjectRoot(process.cwd());
+	if (!app) return root;
+	const rel = relative$1(target, app);
+	if (!rel || rel.startsWith("..") || isAbsolute$1(rel)) return root;
+	return resolve$1(root, rel);
+}
+function registerWarm(worktree) {
+	worktree.command("warm").description("Copy missing ignored paths from the source checkout into the current linked worktree.").option("--refresh", "Before copying, fast-forward the source checkout to its upstream and install what the new commits moved.").action(async (opts) => {
+		try {
+			const { root, target, common } = warmWorktreePaths(process.cwd());
+			const readSettings = () => {
+				const settings = resolveSettings({
+					gitCommonDir: common,
+					repoRoot: root
+				});
+				const shapeErrors = settingShapeErrors(settings);
+				if (shapeErrors.length) {
+					for (const message of shapeErrors) console.error(chalk.red(message));
+					console.error(chalk.dim(SETTING_SHAPE_REMEDY));
+					return null;
+				}
+				for (const key of unknownSettingKeys(settings)) console.error(chalk.yellow(`Warning: setting "${key}" is not read by Stim and will be ignored.`));
+				return settings;
+			};
+			if (opts.refresh) {
+				const settings = readSettings();
+				if (!settings) {
+					process.exitCode = 1;
+					return;
+				}
+				const failure = await withWarmClaim({
+					repositoryRoot: root,
+					phase: "refresh",
+					out: console.error
+				}, (hold) => {
+					console.error(warmClaimAcquiredLine(hold.wait));
+					return refreshMainCheckout({
+						root,
+						appDir: mainCheckoutAppDir(root, target),
+						settings,
+						emit: (line) => console.error(line),
+						installer: hold.installer
+					});
+				});
+				if (failure) {
+					reportRefreshFailure(failure);
+					return;
+				}
+			}
+			const copy = (wait) => {
+				if (wait?.holder) console.error(warmClaimAcquiredLine(wait));
+				const incomplete = incompleteInstallRefusal(root, mainCheckoutAppDir(root, target));
+				if (incomplete) {
+					reportRefreshFailure(incomplete);
+					return;
+				}
+				const settings = readSettings();
+				if (!settings) {
+					process.exitCode = 1;
+					return;
+				}
+				const excluded = readWorktreeExclude(root);
+				const patterns = excluded?.length ? excluded : settings.worktree?.exclude || [];
+				const result = cloneIgnoredEntries({
+					root,
+					target,
+					patterns
+				});
+				for (const entry of result.skipped) console.error(chalk.dim(phaseLine("carry", `kept ${entry.file} (${entry.reason})`)));
+				for (const entry of result.failed) console.error(chalk.yellow(phaseLine("carry", `could not copy ${entry.file}: ${entry.error}`)));
+				if (result.copied.length) {
+					console.error(chalk.dim(phaseLine("carry", `copied ${carriedFileList(result.copied)} from ${root}`)));
+					reportCarriedStateHealth(root, target, result.copied);
+				}
+				console.error(phaseLine("carry", `${result.failed.length ? "incomplete" : "complete"}: ${result.copied.length} ignored entries copied, ${result.skipped.length} kept, ${result.failed.length} failed`));
+				if (result.failed.length) process.exitCode = 1;
+			};
+			let hold = null;
+			try {
+				hold = await acquireWarmClaim({
+					repositoryRoot: root,
+					phase: "copy",
+					out: console.error
+				});
+			} catch (error) {
+				const degraded = opts.refresh ? null : warmClaimDegradation(error);
+				if (degraded === null) throw error;
+				const blocker = warmClaimBlocker(root);
+				if (blocker) {
+					console.error(chalk.dim(warmClaimBlockedLine(degraded, blocker)));
+					console.error(chalk.red(warmClaimBlockedRefusal(blocker)));
+					throw error;
+				}
+				console.error(chalk.dim(warmClaimUnavailableLine(degraded)));
+			}
+			if (!hold) copy(null);
+			else try {
+				copy(hold.wait);
+			} finally {
+				hold.release();
+			}
+		} catch (error) {
+			const code = error?.code;
+			console.error(chalk.red(`Could not warm this worktree: ${error.message}`));
+			const claim = claimFailure(error, `stim worktree warm${opts.refresh ? " --refresh" : ""}`);
+			if (claim) console.error(chalk.dim(claim.remedy));
+			if (typeof code === "string" && code.startsWith("STIM_")) console.error(chalk.red(`failed: ${code}`));
+			process.exitCode = 1;
+		}
+	});
+}
+function carriedFileList(files) {
+	const shown = files.slice(0, 3).join(", ");
+	return files.length > 3 ? `${shown}, +${files.length - 3}` : shown;
+}
+function porcelainPath(line) {
+	const raw = String(line).slice(3).trim();
+	if (raw === "") return null;
+	return (raw.includes(" -> ") ? raw.slice(raw.lastIndexOf(" -> ") + 4) : raw).replace(/^"(.*)"$/, "$1");
+}
+const SAFE_DIFF_PATH = /^[A-Za-z0-9._/-]+$/;
+const POD_CHURN_PATH = /(?:^|\/)ios\/(?:Podfile\.lock|[^/]+\.xcodeproj\/project\.pbxproj)$/;
+function excludePodChurn(lines) {
+	const kept = [];
+	const restore = [];
+	for (const line of lines || []) {
+		const path = porcelainPath(line);
+		if (path && String(line).startsWith(" M ") && SAFE_DIFF_PATH.test(path) && POD_CHURN_PATH.test(path)) {
+			restore.push(path);
+			continue;
+		}
+		kept.push(line);
+	}
+	if (kept.length) return {
+		lines: lines ? [...lines] : [],
+		restore: []
+	};
+	return {
+		lines: kept,
+		restore
+	};
+}
+function matchWorktreeEntry(entries, path) {
+	let best = null;
+	(entries || []).forEach((entry, index) => {
+		if (!entry?.path || !isPathPrefix(entry.path, path)) return;
+		if (!best || entry.path.length > best.path.length) best = {
+			...entry,
+			index
+		};
+	});
+	return best;
+}
+function removalRemedy(dirtyLines, { worktree = "<worktree>" } = {}) {
+	const tracked = [];
+	const untracked = [];
+	for (const line of dirtyLines || []) {
+		if (porcelainPath(line) === null) continue;
+		(String(line).startsWith("??") ? untracked : tracked).push(line);
+	}
+	const lines = [];
+	if (tracked.length) {
+		if (isPodInstallChurn(tracked)) {
+			lines.push("That is only the files `pod install` rewrites. Restore them and retry:");
+			lines.push(`  git -C ${worktree} checkout -- ${pathArgs(tracked)}`);
+		} else {
+			lines.push("Tracked files were modified -- if a build or a setup script did it, restore them and retry:");
+			lines.push(`  git -C ${worktree} checkout -- ${pathArgs(tracked)}`);
+		}
+	}
+	if (untracked.length) {
+		lines.push("Untracked files are also present -- `git checkout` cannot clear those. Delete them and retry:");
+		lines.push(`  git -C ${worktree} clean -fd ${pathArgs(untracked)}        # or rm them yourself`);
+	}
+	return lines;
+}
+function pathArgs(lines, limit = 5) {
+	const paths = (lines || []).map(porcelainPath).filter((p) => Boolean(p));
+	const shown = paths.slice(0, limit).map((p) => /[\s"'\\$`]/.test(p) ? JSON.stringify(p) : p);
+	return `${shown.join(" ")}${paths.length > shown.length ? " ..." : ""}`;
+}
+function removalBlockers({ dirty, unpushed }) {
+	const blockers = [];
+	if (dirty === null || unpushed === null) blockers.push("could not determine git status; re-run with --force to override");
+	if (dirty) blockers.push("uncommitted changes or untracked files");
+	if (unpushed && unpushed.length) blockers.push(`${plural(unpushed.length, "commit")} not on any remote or any other local branch`);
+	return blockers;
+}
+function describeKeptDevice(s) {
+	return s.udid && s.udid !== s.name ? `${s.name} (${s.udid})` : s.name;
+}
+function reclaimKeys(rootPath) {
+	const cfg = loadConfig();
+	const keys = /* @__PURE__ */ new Set([rootPath]);
+	if (cfg?.projects) {
+		for (const key of Object.keys(cfg.projects)) if (isPathPrefix(rootPath, key)) keys.add(key);
+	}
+	return [...keys].toSorted();
+}
+async function withReclaimLocks(rootPath, fn) {
+	const keys = reclaimKeys(rootPath);
+	const acquire = (index) => index === keys.length ? fn(keys) : withManagedTunnelRemovalLock(keys[index], () => acquire(index + 1));
+	return acquire(0);
+}
+async function reclaimAll(rootPath, keys = reclaimKeys(rootPath), { preserveRootProject = false } = {}) {
+	const dereferenced = [];
+	const killedPids = [];
+	const deletedDevices = [];
+	const parkedDevices = [];
+	const evictedDevices = [];
+	const poolNotes = [];
+	const skippedDevices = [];
+	const keptEntries = [];
+	const retainedResources = [];
+	const stoppedSessions = [];
+	const stoppedTunnels = [];
+	const releasedLeases = [];
+	const removedWorkspaceDirs = [];
+	const failedWorkspaceDirs = [];
+	for (const key of keys) {
+		const r = await reclaimProject(key, {
+			deleteOwnedDevices: true,
+			parkOwnedDevices: true,
+			preserveProjectRecord: preserveRootProject && key === rootPath
+		});
+		dereferenced.push(...r.dereferenced);
+		if (r.killedPid) killedPids.push(r.killedPid);
+		deletedDevices.push(...r.deletedDevices);
+		parkedDevices.push(...r.parkedDevices);
+		evictedDevices.push(...r.evictedDevices);
+		poolNotes.push(...r.poolNotes);
+		skippedDevices.push(...r.skippedDevices);
+		if (r.stoppedSession) stoppedSessions.push(r.stoppedSession);
+		if (r.stoppedTunnel) stoppedTunnels.push(r.stoppedTunnel);
+		releasedLeases.push(...r.releasedLeases);
+		removedWorkspaceDirs.push(...r.removedWorkspaceDirs);
+		failedWorkspaceDirs.push(...r.failedWorkspaceDirs);
+		if (r.keptEntry) {
+			keptEntries.push(key);
+			for (const resource of r.failedDevices) retainedResources.push({
+				...resource,
+				project: key
+			});
+		}
+	}
+	for (const key of keys) {
+		if (keptEntries.includes(key)) continue;
+		const tunnel = readMetroTunnel(key);
+		const managedTunnel = tunnel?.kind === "managed" ? tunnel : null;
+		const remote = readRemoteSession(key);
+		if (!managedTunnel && !remote) continue;
+		keptEntries.push(key);
+		retainedResources.push({
+			platform: remote?.platform ?? "ios",
+			name: remote ? `remote session ${remote.sessionId}` : `${managedTunnel?.provider ?? "managed"} tunnel`,
+			reason: "A remote ownership record appeared during reclaim and is retained for a later cleanup.",
+			project: key
+		});
+	}
+	for (const key of reclaimKeys(rootPath)) {
+		if (keys.includes(key) || keptEntries.includes(key)) continue;
+		keptEntries.push(key);
+		retainedResources.push({
+			name: "new project ownership state",
+			reason: "The project was registered after removal acquired its locks. Retry removal after the other command finishes.",
+			project: key
+		});
+	}
+	return {
+		dereferenced,
+		killedPids,
+		deletedDevices,
+		parkedDevices,
+		evictedDevices,
+		poolNotes,
+		parkedMax: {
+			ios: parkedMaxSetting("ios").max,
+			android: parkedMaxSetting("android").max
+		},
+		skippedDevices,
+		keptEntries,
+		retainedResources,
+		reclaimedKeys: [...keys],
+		stoppedSessions,
+		stoppedTunnels,
+		releasedLeases,
+		removedWorkspaceDirs,
+		failedWorkspaceDirs
+	};
+}
+function poolLines(result) {
+	const lines = [];
+	for (const device of result.parkedDevices) lines.push(chalk.dim(phaseLine("device", `parked ${device.name}${device.platform === "android" ? "" : ` (${shortUdid(device.udid)})`}`)));
+	for (const device of result.evictedDevices) lines.push(chalk.dim(phaseLine("device", `deleted ${device.name} (pool over ${result.parkedMax[device.platform ?? "ios"]})`)));
+	for (const note of result.poolNotes) lines.push(chalk.yellow(phaseLine("device", note)));
+	return lines;
+}
+function reportRetainedResources(root, result) {
+	console.error(chalk.red(`Refusing to remove ${root}: Stim could not release owned resources.`));
+	for (const resource of result.retainedResources) {
+		console.error(chalk.yellow(`  - Stim still tracks ${describeKeptDevice(resource)} for ${resource.project}`));
+		console.error(chalk.dim(`    ${resource.reason}`));
+	}
+	for (const kept of result.keptEntries) {
+		if (result.retainedResources.some((resource) => resource.project === kept)) continue;
+		console.error(chalk.yellow(`  - retained Stim ownership state for ${kept}`));
+	}
+	console.error(chalk.dim("Fix the reported cause, then run `stim worktree remove` again."));
+	process.exitCode = 1;
+}
+function hasRegisteredProjectUnder(rootPath) {
+	const cfg = loadConfig();
+	return Object.keys(cfg?.projects ?? {}).some((key) => isPathPrefix(rootPath, key));
+}
+async function reclaimEnvironment(root, why) {
+	await withManagedRemoteWorktreeRemovalLock(root, () => withReclaimLocks(root, async (lockedKeys) => {
+		const result = await reclaimAll(root, lockedKeys);
+		for (const line of poolLines(result)) console.error(line);
+		for (const device of result.deletedDevices) console.error(chalk.dim(phaseLine("device", `deleted ${device}`)));
+		for (const session of result.stoppedSessions) console.error(chalk.dim(phaseLine("device", `stopped remote session ${session}`)));
+		for (const tunnel of result.stoppedTunnels) console.error(chalk.dim(phaseLine("lan", `stopped the ${tunnel} tunnel`)));
+		for (const lease of result.releasedLeases) console.error(chalk.dim(phaseLine("lease", releasedLeaseFact(lease))));
+		for (const pid of result.killedPids) console.error(chalk.dim(phaseLine("metro", `killed pid ${pid}`)));
+		for (const dir of result.removedWorkspaceDirs) console.error(chalk.dim(phaseLine("workspace", `removed ${dir}`)));
+		for (const dir of result.failedWorkspaceDirs) console.error(chalk.yellow(phaseLine("workspace", `could not remove ${dir}`)));
+		if (result.dereferenced.length) console.error(chalk.dim(phaseLine("workspace", `no longer referenced: ${result.dereferenced.join(", ")}`)));
+		if (result.keptEntries.length) {
+			reportRetainedResources(root, result);
+			return;
+		}
+		for (const s of result.skippedDevices) console.error(chalk.yellow(phaseLine("device", `kept ${describeKeptDevice(s)} (${s.reason})`)));
+		console.error(chalk.green(`Reclaimed the environment; the working tree stays (${why}).`));
+	}));
+}
+function removalPath(target) {
+	return canonicalExistingPath(target ?? process.cwd());
+}
+function canonicalExistingPath(target) {
+	const resolved = resolve$1(target);
+	let existing = resolved;
+	const missing = [];
+	while (!existsSync$1(existing)) {
+		const parent = dirname$1(existing);
+		if (parent === existing) return resolved;
+		missing.unshift(basename$1(existing));
+		existing = parent;
+	}
+	return resolve$1(realpathSync$1(existing), ...missing);
+}
+function inspectRemoval(path) {
+	const gitAnswered = hasUncommittedWork(path);
+	const { lines: dirtyLines, restore: podChurn } = excludePodChurn(gitAnswered ? dirtyPaths(path, { limit: Infinity }) : []);
+	const dirty = gitAnswered === null ? null : dirtyLines.length > 0;
+	const unpushed = unpushedCommits(path);
+	return {
+		dirtyLines,
+		podChurn,
+		unpushed,
+		blockers: removalBlockers({
+			dirty,
+			unpushed
+		})
+	};
+}
+function printRemovalRefusal(path, inspection) {
+	const { blockers, dirtyLines, unpushed } = inspection;
+	console.error(chalk.red(`Refusing to remove ${path}:`));
+	for (const blocker of blockers) console.error(chalk.red(`  - ${blocker}`));
+	if (unpushed && unpushed.length && !hasRemote(path)) console.error(chalk.dim("  (no remote is configured for this worktree, so every commit no other local branch reaches counts as unpushed)"));
+	for (const line of dirtyLines.slice(0, 10)) console.error(chalk.dim(`      ${line}`));
+	if (dirtyLines.length) console.error(chalk.dim(`  (git -C ${path} status -s for the full list)`));
+	for (const line of removalRemedy(dirtyLines, { worktree: path })) console.error(chalk.dim(line));
+	console.error(chalk.dim("Otherwise: commit or push the branch (only commits found nowhere else are counted,"));
+	console.error(chalk.dim("so pushing publishes nothing but this worktree's own work). --force is a last"));
+	console.error(chalk.dim("resort -- it discards uncommitted changes and untracked files permanently; committed"));
+	console.error(chalk.dim("work stays on the branch."));
+	process.exitCode = 1;
+}
+function restorePodChurn(path, files) {
+	for (const file of files) if (restoreFile(path, file)) console.error(chalk.dim(`  restored ${file} (pod install churn; the worktree is being removed)`));
+	else console.error(chalk.yellow(`  could not restore ${file}; git may refuse to remove the worktree`));
+}
+function printRemovalCleanup(result, failed) {
+	for (const line of poolLines(result)) console.error(line);
+	for (const device of result.deletedDevices) console.error(chalk.dim(phaseLine("device", `deleted ${device}`)));
+	for (const session of result.stoppedSessions) console.error(chalk.dim(phaseLine("device", `stopped remote session ${session}`)));
+	for (const tunnel of result.stoppedTunnels) console.error(chalk.dim(phaseLine("lan", `stopped the ${tunnel} tunnel`)));
+	for (const lease of result.releasedLeases) console.error(chalk.dim(phaseLine("lease", releasedLeaseFact(lease))));
+	for (const pid of result.killedPids) console.error(chalk.dim(phaseLine("metro", `killed pid ${pid}`)));
+	if (!failed) for (const dir of result.removedWorkspaceDirs) console.error(chalk.dim(phaseLine("workspace", `removed ${dir}`)));
+	if (result.dereferenced.length) console.error(chalk.dim(phaseLine("workspace", `no longer referenced: ${result.dereferenced.join(", ")}`)));
+	for (const skipped of result.skippedDevices) console.error((failed ? chalk.dim : chalk.yellow)(phaseLine("device", `kept ${describeKeptDevice(skipped)} (${skipped.reason})`)));
+}
+async function runRemove(target, opts = {}) {
+	const poolError = parkedMaxSetting("ios").error || parkedMaxSetting("android").error;
+	if (poolError) {
+		console.error(chalk.red(poolError));
+		console.error(chalk.dim(POOL_SETTING_REMEDY));
+		process.exitCode = 1;
+		return;
+	}
+	let path = removalPath(target);
+	if (!existsSync$1(path)) {
+		const pending = getProject(path);
+		if (pending?.worktreeRemovalComplete === true && pending.worktreeBranchOwned === true && pending.worktreeBranch && pending.worktreeMainRoot && pending.worktreePendingBranchSha) {
+			const branch = pending.worktreeBranch;
+			const mainRoot = pending.worktreeMainRoot;
+			if (!existsSync$1(mainRoot)) {
+				console.error(chalk.red(`Cannot finish branch cleanup for ${path}: source checkout ${mainRoot} is missing.`));
+				console.error(chalk.dim(`Delete ${branch} from the repository, then run \`stim gc --delete\`.`));
+				process.exitCode = 1;
+				return;
+			}
+			if (!branchExists(mainRoot, branch)) {
+				removeProject(path);
+				console.error(chalk.dim(phaseLine("branch", `${branch} is already absent; cleared its pending cleanup record`)));
+				return;
+			}
+			const checkedOutAt = listWorktrees(mainRoot).find((candidate) => candidate.branch === branch && resolve$1(candidate.path) !== resolve$1(path))?.path;
+			if (checkedOutAt) {
+				console.error(chalk.red(`Refusing pending cleanup for ${branch}: it is checked out at ${checkedOutAt}.`));
+				console.error(chalk.dim("Switch that worktree to another branch, then retry this command."));
+				process.exitCode = 1;
+				return;
+			}
+			const currentSha = resolveFullRef(mainRoot, branch);
+			if (currentSha !== pending.worktreePendingBranchSha) {
+				console.error(chalk.red(`Refusing pending cleanup for ${branch}: its tip changed from ${pending.worktreePendingBranchSha} to ${currentSha || "an unknown commit"}.`));
+				console.error(chalk.dim("The branch can contain new work. Inspect it and delete it manually if appropriate."));
+				process.exitCode = 1;
+				return;
+			}
+			try {
+				deleteBranch(mainRoot, branch, pending.worktreePendingBranchSha);
+				removeProject(path);
+				console.error(chalk.dim(phaseLine("branch", `deleted ${branch}; cleared its pending cleanup record`)));
+			} catch (error) {
+				console.error(chalk.red(`Could not delete branch ${branch}: ${String(error?.message || error)}`));
+				console.error(chalk.dim(`Retry with: stim worktree remove ${path}`));
+				process.exitCode = 1;
+			}
+			return;
+		}
+		console.error(chalk.red(`No such worktree: ${path}`));
+		process.exitCode = 1;
+		return;
+	}
+	const worktrees = listWorktrees(path);
+	const entry = matchWorktreeEntry(worktrees, path);
+	if (!entry) {
+		if (gitCommonDir(path) === null && hasRegisteredProjectUnder(path)) {
+			await reclaimEnvironment(path, "it is not a git repository");
+			return;
+		}
+		console.error(chalk.red(`Refusing to remove ${path}: it is not inside any worktree known to git.`));
+		console.error(chalk.dim("  Run it from inside the worktree, or pass the worktree root path, e.g. as printed by `git worktree list`."));
+		process.exitCode = 1;
+		return;
+	}
+	if (isMainWorkingTree(entry.path)) {
+		if (entry.path !== path) console.error(chalk.dim(`${path} is inside the source checkout ${entry.path}; reclaiming its environment.`));
+		await reclaimEnvironment(entry.path, "it is the source checkout");
+		return;
+	}
+	if (entry.path !== path) {
+		console.error(chalk.dim(`${path} is inside the worktree ${entry.path}; removing that.`));
+		path = entry.path;
+	}
+	const project = getProject(path);
+	const branch = entry.branch;
+	const ownsBranch = Boolean(branch && project?.worktreeBranchOwned === true && project.worktreeBranch === branch);
+	const approvedBranchSha = ownsBranch ? resolveFullRef(path, "HEAD") : null;
+	const inspection = inspectRemoval(path);
+	if (inspection.blockers.length && !opts.force) {
+		printRemovalRefusal(path, inspection);
+		return;
+	}
+	const deleteOwnedBranch = Boolean(ownsBranch && approvedBranchSha && inspection.unpushed?.length === 0);
+	const retainedBranchReason = !branch ? null : !ownsBranch ? "Stim did not create it" : inspection.unpushed === null ? "Stim could not verify whether it has unique commits" : inspection.unpushed.length > 0 ? `it has ${plural(inspection.unpushed.length, "unique commit")}` : null;
+	const branchDeleteCwd = worktrees.find((candidate) => isMainWorkingTree(candidate.path))?.path;
+	await withManagedRemoteWorktreeRemovalLock(path, () => withReclaimLocks(path, async (lockedKeys) => {
+		const result = await reclaimAll(path, lockedKeys, { preserveRootProject: true });
+		if (result.keptEntries.length) {
+			reportRetainedResources(path, result);
+			return;
+		}
+		restorePodChurn(path, inspection.podChurn);
+		try {
+			removeWorktree(path, { force: opts.force });
+		} catch (error) {
+			console.error(chalk.red(`git worktree remove failed: ${String(error?.message || error)}`));
+			console.error(chalk.dim(`The directory and Stim ownership record for ${path} were kept.`));
+			printRemovalCleanup(result, true);
+			process.exitCode = 1;
+			return;
+		}
+		const finish = () => {
+			printRemovalCleanup(result, false);
+			console.error(chalk.dim(phaseLine("removed", path)));
+		};
+		if (deleteOwnedBranch && branch) {
+			if (!approvedBranchSha) {
+				console.error(chalk.yellow(phaseLine("branch", `kept ${branch} (Stim could not record its commit before removal)`)));
+				process.exitCode = 1;
+				finish();
+				return;
+			}
+			upsertProject(path, {
+				worktreeRemovalComplete: true,
+				worktreePendingBranchSha: approvedBranchSha
+			});
+			if (!branchDeleteCwd) {
+				console.error(chalk.yellow(phaseLine("branch", `kept ${branch} (Stim could not find the source checkout)`)));
+				console.error(chalk.dim(`  Retry with: stim worktree remove ${path}`));
+				process.exitCode = 1;
+				finish();
+				return;
+			}
+			const checkedOutAt = listWorktrees(branchDeleteCwd).find((candidate) => candidate.branch === branch && resolve$1(candidate.path) !== resolve$1(path))?.path;
+			if (checkedOutAt) {
+				console.error(chalk.yellow(phaseLine("branch", `kept ${branch} (it is checked out at ${checkedOutAt})`)));
+				console.error(chalk.dim(`  Switch that worktree to another branch, then retry: stim worktree remove ${path}`));
+				process.exitCode = 1;
+				finish();
+				return;
+			}
+			try {
+				deleteBranch(branchDeleteCwd, branch, approvedBranchSha);
+				console.error(chalk.dim(phaseLine("branch", `deleted ${branch}`)));
+			} catch (error) {
+				console.error(chalk.yellow(phaseLine("branch", `kept ${branch} (${String(error?.message || error)})`)));
+				console.error(chalk.dim(`  Retry with: git -C ${branchDeleteCwd} branch -D -- ${branch}`));
+				process.exitCode = 1;
+				finish();
+				return;
+			}
+		} else if (branch && retainedBranchReason) console.error(chalk.dim(phaseLine("branch", `kept ${branch} (${retainedBranchReason})`)));
+		removeProject(path);
+		finish();
+	}));
+}
+function registerRemove(worktree) {
+	worktree.command("remove [target]").description("Remove a worktree, its unused Stim-created branch, build artifacts, owned devices, and Metro port. Defaults to the current workspace. On the source checkout it reclaims the environment only and leaves the tree in place.").option("--force", "remove even when the worktree holds uncommitted or unpushed work").action(runRemove);
+}
+function worktreeCommand(program) {
+	const worktree = program.command("worktree").description("Warm and remove Git worktrees");
+	registerWarm(worktree);
+	registerRemove(worktree);
+}
+//#endregion
+export { worktreeCommand as default, dependencyInstallCommand, excludePodChurn, matchWorktreeEntry, porcelainPath, registerRemove, registerWarm, removalBlockers, removalPath, removalRemedy };