dsh-worktree-switch 0.3.1 → 0.5.0

package/lib/index.js

@@ -1,6 +1,6 @@
 import Schema from "@deepseek-ai/schemastery";
-import { basename, dirname, isAbsolute, relative, resolve } from "node:path";
-import { lstat, realpath, stat } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { lstat, readFile, realpath, stat, writeFile } from "node:fs/promises";
 // src/host/paths.ts
 /**
 * Path predicates the host half shares between the verbs, the scope hint, and
@@ -280,6 +280,243 @@ async function changedFileCount(ctx, directory, signal) {
 		"--untracked-files=normal"
 	], { signal })).stdout.split("\n").filter((line) => line.trim() !== "").length;
 }
+/**
+* Resolve the whereabouts of one checkout's Git administration directory.
+*
+* A linked worktree's `.git` is a file pointing at
+* `<common>/worktrees/<name>`; this is the directory Git owns for that one
+* checkout, which is where the switch records its claim on the copy.
+* @param ctx - Host context carrying the subprocess provider.
+* @param checkout - absolute directory of the checkout to ask.
+* @param signal - caller cancellation.
+* @returns the absolute admin directory Git reports.
+* @throws {GitFailure} when the directory is not inside a Git working tree.
+*/
+async function absoluteGitDir(ctx, checkout, signal) {
+	const result = await runGit(ctx, checkout, ["rev-parse", "--absolute-git-dir"], { signal });
+	const path = result.stdout.replace(/\r?\n$/, "");
+	if (path === "") throw new GitFailure(["rev-parse", "--absolute-git-dir"], result);
+	return path;
+}
+/**
+* Read the branch one checkout has checked out.
+* @param ctx - Host context carrying the subprocess provider.
+* @param checkout - absolute directory of the checkout to ask.
+* @param signal - caller cancellation.
+* @returns the branch name, or null when the checkout is on a detached HEAD.
+*/
+async function currentBranch(ctx, checkout, signal) {
+	const result = await runGit(ctx, checkout, [
+		"symbolic-ref",
+		"--short",
+		"--quiet",
+		"HEAD"
+	], {
+		signal,
+		allowedExitCodes: [0, 1]
+	});
+	const name = result.stdout.replace(/\r?\n$/, "");
+	return result.exitCode === 0 && name !== "" ? name : null;
+}
+/**
+* Resolve one revision to the commit id it names.
+* @param ctx - Host context carrying the subprocess provider.
+* @param directory - checkout the command runs in.
+* @param revision - revision to resolve; `HEAD` or a full id are the usual values.
+* @param signal - caller cancellation.
+* @returns the commit id, or null when the revision does not resolve.
+*/
+async function revParse(ctx, directory, revision, signal) {
+	const result = await runGit(ctx, directory, [
+		"rev-parse",
+		"--verify",
+		"--quiet",
+		revision
+	], {
+		signal,
+		allowedExitCodes: [
+			0,
+			1,
+			128
+		]
+	});
+	const id = result.stdout.replace(/\r?\n$/, "");
+	return result.exitCode === 0 && id !== "" ? id : null;
+}
+/**
+* Count the commits in one revision range.
+* @param ctx - Host context carrying the subprocess provider.
+* @param directory - checkout the command runs in.
+* @param range - the range to count, e.g. `HEAD..refs/heads/<branch>`.
+* @param signal - caller cancellation.
+* @returns the number of commits in the range.
+* @throws {GitFailure} when the range does not resolve.
+*/
+async function revListCount(ctx, directory, range, signal) {
+	const result = await runGit(ctx, directory, [
+		"rev-list",
+		"--count",
+		range
+	], { signal });
+	const count = Number.parseInt(result.stdout.trim(), 10);
+	return Number.isFinite(count) ? count : 0;
+}
+/**
+* Parse `git for-each-ref` output produced with the NUL-separated format below.
+* @param stdout - the command's stdout.
+* @returns one entry per local branch, in Git's order.
+*/
+function parseBranchRefs(stdout) {
+	const refs = [];
+	for (const line of stdout.split("\n")) {
+		if (line === "") continue;
+		const [name, commit, seconds, subject] = line.split("\0");
+		if (name === void 0 || commit === void 0 || seconds === void 0 || subject === void 0) continue;
+		const committedAt = Number.parseInt(seconds, 10) * 1e3;
+		refs.push({
+			name,
+			commit,
+			committedAt: Number.isFinite(committedAt) ? committedAt : 0,
+			subject
+		});
+	}
+	return refs;
+}
+/**
+* List the local branches of one repository.
+* @param ctx - Host context carrying the subprocess provider.
+* @param root - repository root the command runs in.
+* @param signal - caller cancellation.
+* @returns every local branch with its tip commit.
+*/
+async function listBranchRefs(ctx, root, signal) {
+	return parseBranchRefs((await runGit(ctx, root, [
+		"for-each-ref",
+		"--format=%(refname:short)%00%(objectname)%00%(committerdate:unix)%00%(subject)",
+		"refs/heads"
+	], { signal })).stdout);
+}
+// src/host/base.ts
+/** Whole-command deadline for the plugin's one network call. */
+const FETCH_TIMEOUT_MS = 5e3;
+/** Local HEAD, used by `head` mode and by every silent failure. */
+const LOCAL_HEAD = {
+	from: "HEAD",
+	base: { kind: "head" }
+};
+/**
+* Resolve the default branch `origin` advertises, if it has one.
+*
+* `origin/HEAD` is the clone's own answer; clones that lost it still commonly
+* default to `main` or `master`, so those two are probed before giving up. A
+* repository with no `origin` is a normal local-only project, not a failure:
+* the caller skips fetching entirely and leaves no notice behind.
+* @param ctx - Host context carrying the subprocess provider.
+* @param root - canonical repository root to ask.
+* @param signal - caller cancellation.
+* @returns the branch name without its `origin/` prefix, or null.
+*/
+async function defaultBranch(ctx, root, signal) {
+	const remote = await runGit(ctx, root, [
+		"remote",
+		"get-url",
+		"origin"
+	], {
+		signal,
+		allowedExitCodes: [
+			0,
+			1,
+			2
+		]
+	});
+	if (remote.exitCode !== 0 || remote.stdout.trim() === "") return null;
+	const symbolic = await runGit(ctx, root, [
+		"symbolic-ref",
+		"--short",
+		"refs/remotes/origin/HEAD"
+	], {
+		signal,
+		allowedExitCodes: [
+			0,
+			1,
+			128
+		]
+	});
+	if (symbolic.exitCode === 0) {
+		const name = symbolic.stdout.trim();
+		if (name.startsWith("origin/") && name.length > 7) return name.slice(7);
+	}
+	for (const candidate of ["main", "master"]) {
+		const known = await runGit(ctx, root, [
+			"rev-parse",
+			"--verify",
+			"--quiet",
+			`refs/remotes/origin/${candidate}`
+		], {
+			signal,
+			allowedExitCodes: [0, 1]
+		});
+		if (known.exitCode === 0 && known.stdout.trim() !== "") return candidate;
+	}
+	return null;
+}
+/**
+* Choose the base commit for a copy that is about to be created.
+*
+* `head` mode never touches the network. `fresh` mode fetches only the default
+* branch, with an explicit refspec so a rewritten `remote.origin.fetch` cannot
+* silently skip the update, and returns the fetched commit itself rather than
+* the ref name: another process may advance the ref between the fetch and the
+* worktree service's checkout.
+* @param ctx - Host context carrying the subprocess provider.
+* @param root - canonical repository root the fetch runs in.
+* @param baseRef - configured base point.
+* @param signal - caller cancellation; distinct from the fetch deadline.
+* @returns the revision to create from and the outcome to report.
+* @throws when the caller cancels; every Git failure is contained.
+*/
+async function resolveBase(ctx, root, baseRef, signal) {
+	if (baseRef === "head") return LOCAL_HEAD;
+	let branch;
+	try {
+		branch = await defaultBranch(ctx, root, signal);
+	} catch {
+		signal?.throwIfAborted();
+		return LOCAL_HEAD;
+	}
+	if (branch === null) return LOCAL_HEAD;
+	try {
+		await runGit(ctx, root, [
+			"fetch",
+			"--no-tags",
+			"--quiet",
+			"origin",
+			`+refs/heads/${branch}:refs/remotes/origin/${branch}`
+		], {
+			signal,
+			timeoutMs: FETCH_TIMEOUT_MS
+		});
+		const from = (await runGit(ctx, root, [
+			"rev-parse",
+			"--verify",
+			`refs/remotes/origin/${branch}^{commit}`
+		], { signal })).stdout.trim();
+		if (from === "") throw new Error(`origin/${branch} has no commit after fetching it`);
+		return {
+			from,
+			base: {
+				kind: "remote",
+				branch
+			}
+		};
+	} catch {
+		signal?.throwIfAborted();
+		return {
+			from: "HEAD",
+			base: { kind: "fallback" }
+		};
+	}
+}
 // src/host/naming.ts
 /**
 * Names for the copy a session gets: lowercase words and a short suffix, so a
@@ -367,6 +604,19 @@ function worktreeName(random = Math.random) {
 }
 /** A pool entry name is exactly one path segment, as `git worktree` names it. */
 const NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** The shape this plugin generates: two lowercase words and four hex digits. */
+const GENERATED_PATTERN = /^[a-z]+-[a-z]+-[0-9a-f]{4}$/;
+/**
+* Whether a branch name looks like one this plugin generated.
+*
+* Leftover-branch cleanup only offers names of this shape: an ordinary feature
+* branch is never a candidate, even when no checkout holds it.
+* @param value - candidate branch name.
+* @returns true for the generated-name format.
+*/
+function isGeneratedName(value) {
+	return GENERATED_PATTERN.test(value);
+}
 /**
 * Validate a worktree name received from the browser before it reaches Git.
 * @param value - candidate name.
@@ -375,9 +625,66 @@ const NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 function isWorktreeName(value) {
 	return NAME_PATTERN.test(value) && !value.endsWith(".lock");
 }
+// src/host/ownership.ts
+/**
+* The switch's claim on a copy.
+*
+* "This copy was created by the switch for this session" used to live only in
+* host memory, so a host restart turned every copy into a stranger and the
+* leave path could never prove it was safe to undo. The claim is now stored in
+* the checkout's own Git administration directory: it travels with the copy,
+* vanishes when the copy is deleted, never appears in the working tree, and
+* survives a restart. A missing or unparseable marker means "not owned" — the
+* plugin does not guess, because guessing wrong deletes work.
+* @module dsh-worktree-switch/host/ownership
+*/
+/** File name inside the checkout's admin directory. */
+const MARKER_FILE = "dsh-worktree-switch.json";
+/**
+* Read one checkout's ownership marker.
+*
+* Every failure — no admin directory, no marker, invalid JSON, a shape this
+* version does not understand — reads as "no claim". The leave path treats
+* that as a reason to keep the copy, never as a reason to take it.
+* @param ctx - Host context carrying the subprocess provider.
+* @param checkout - absolute directory of the copy.
+* @param signal - caller cancellation.
+* @returns the recorded claim, or null when there is none.
+*/
+async function readOwnership(ctx, checkout, signal) {
+	try {
+		const directory = await absoluteGitDir(ctx, checkout, signal);
+		const raw = await readFile(join(directory, MARKER_FILE), "utf8");
+		const parsed = JSON.parse(raw);
+		if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+		const { sessionId, createdAt, baseCommit } = parsed;
+		if (typeof sessionId !== "string" || sessionId === "") return null;
+		if (typeof createdAt !== "number" || !Number.isFinite(createdAt)) return null;
+		if (typeof baseCommit !== "string" || baseCommit === "") return null;
+		return {
+			sessionId,
+			createdAt,
+			baseCommit
+		};
+	} catch {
+		return null;
+	}
+}
+/**
+* Record the switch's claim on a freshly created copy.
+* @param ctx - Host context carrying the subprocess provider.
+* @param checkout - absolute directory of the copy.
+* @param ownership - the claim to write.
+* @param signal - caller cancellation.
+* @throws when the admin directory cannot be resolved or the marker cannot be written.
+*/
+async function writeOwnership(ctx, checkout, ownership, signal) {
+	const directory = await absoluteGitDir(ctx, checkout, signal);
+	await writeFile(join(directory, MARKER_FILE), `${JSON.stringify(ownership)}\n`, "utf8");
+}
 // src/host/handlers.ts
 /**
-* The plugin's host Remote face: the five verbs the browser half can call,
+* The plugin's host Remote face: the verbs the browser half can call,
 * expressed against a live session and the checkouts on disk.
 *
 * This module is the seam the host tests drive directly. Everything below it —
@@ -404,6 +711,16 @@ var WorktreeToggleError = class extends Error {
 		this.name = "WorktreeToggleError";
 	}
 };
+/**
+* The failure one refused branch delete reports.
+* @param branch - branch the verb tried to delete.
+* @param args - the Git command that refused, for the message.
+* @param result - its captured outcome.
+* @returns the error the browser half switches on.
+*/
+function branchDeleteFailure(branch, args, result) {
+	return new WorktreeToggleError("branch-delete-failed", new GitFailure(args, result).message, { branch });
+}
 /** Normalize a browser-supplied path before any filesystem work. */
 function absolutePath(value) {
 	const trimmed = value.trim();
@@ -418,11 +735,13 @@ function absolutePath(value) {
 * from any configured pool path. The pool belongs to the harness worktree
 * service, so this plugin never needs a second copy of that setting: moving the
 * pool in the service's row config keeps every verb working.
+* @param ctx - host context carrying `subprocess`.
 * @param current - the session's committed working directory.
 * @param repositoryRoot - canonical root of the project's repository.
+* @param signal - caller cancellation.
 * @returns the copy's identity, or null when the directory is not one.
 */
-async function worktreeAt(current, repositoryRoot) {
+async function worktreeAt(ctx, current, repositoryRoot, signal) {
 	const path = await canonicalPath(current);
 	if (path === repositoryRoot) return null;
 	const inside = relative(repositoryRoot, path);
@@ -437,7 +756,7 @@ async function worktreeAt(current, repositoryRoot) {
 	return {
 		name,
 		path,
-		branch: name
+		branch: await currentBranch(ctx, path, signal)
 	};
 }
 /**
@@ -477,7 +796,7 @@ async function detectSessionScope(ctx, agent, signal) {
 	signal?.throwIfAborted();
 	let probe = current;
 	for (;;) {
-		const copy = await worktreeAt(probe, root);
+		const copy = await worktreeAt(ctx, probe, root, signal);
 		if (copy !== null) return {
 			worktree: copy,
 			repositoryRoot: root
@@ -488,21 +807,111 @@ async function detectSessionScope(ctx, agent, signal) {
 	}
 }
 /**
+* The copy rows of one repository, newest first.
+*
+* A row whose checkout directory is gone is still a copy: Git keeps the
+* registration until it is pruned, and the panel offers the same discard for
+* it, marked as missing. A detached copy keeps `branch: null` so no verb can
+* ever mistake the directory name for a branch to delete.
+* @param ctx - host context carrying `subprocess`.
+* @param root - canonical repository root.
+* @param records - `git worktree list` records for the repository.
+* @param signal - caller cancellation.
+* @returns one row per copy under the project.
+*/
+async function copyItems(ctx, root, records, signal) {
+	const items = [];
+	for (const record of records) {
+		signal?.throwIfAborted();
+		const path = await canonicalPath(record.path);
+		if (path === root) continue;
+		const name = basename(path);
+		if (!isWorktreeName(name)) continue;
+		let createdAt = 0;
+		let prunable = true;
+		try {
+			const info = await stat(path);
+			createdAt = Math.trunc(info.birthtimeMs > 0 ? info.birthtimeMs : info.mtimeMs);
+			prunable = false;
+		} catch {}
+		const changedFiles = prunable ? 0 : await changedFileCount(ctx, path, signal);
+		items.push({
+			name,
+			path,
+			branch: record.branch ?? null,
+			createdAt,
+			changedFiles,
+			prunable
+		});
+	}
+	items.sort((left, right) => right.createdAt - left.createdAt || left.name.localeCompare(right.name));
+	return items;
+}
+/**
+* Generated-name branches that no checkout holds.
+*
+* Deliberately narrow: only the names this plugin generates qualify, so an
+* ordinary feature branch never appears in a list whose only action is delete.
+* The commit count is what the source checkout's HEAD does not contain — a
+* branch whose work is fully merged reads as 0, which is the one safe signal.
+* @param ctx - host context carrying `subprocess`.
+* @param root - canonical repository root.
+* @param records - `git worktree list` records for the repository.
+* @param signal - caller cancellation.
+* @returns the leftover branches, newest commit first.
+*/
+async function orphanBranches(ctx, root, records, signal) {
+	const checkedOut = /* @__PURE__ */ new Set();
+	for (const record of records) if (record.branch !== void 0) checkedOut.add(record.branch);
+	const orphans = [];
+	for (const ref of await listBranchRefs(ctx, root, signal)) {
+		signal?.throwIfAborted();
+		if (!isGeneratedName(ref.name) || checkedOut.has(ref.name)) continue;
+		let commits = 0;
+		try {
+			commits = await revListCount(ctx, root, `HEAD..${ref.commit}`, signal);
+		} catch {}
+		orphans.push({
+			branch: ref.name,
+			commits,
+			subject: ref.subject,
+			committedAt: ref.committedAt
+		});
+	}
+	orphans.sort((left, right) => right.committedAt - left.committedAt || left.branch.localeCompare(right.branch));
+	return orphans;
+}
+/** The wire identity of one listed copy; a detached copy keeps its null branch. */
+function copyRef(item) {
+	return {
+		name: item.name,
+		path: item.path,
+		branch: item.branch
+	};
+}
+/**
 * Build the host face.
 * @param ctx - Host context with `agents`, `worktrees`, `workingDirectory`, and `subprocess`.
 * @param options - resolved row config.
-* @returns the five verbs.
+* @returns the verbs above.
 */
 function createWorktreeToggle(ctx, options) {
 	/** One in-flight preparation per session, so a double mount cannot create twice. */
 	const pending = /* @__PURE__ */ new Map();
 	/**
-	* Copies this host instance created for a session, by session id. Turning the
-	* switch off may only delete what the switch itself just made: a copy that
-	* existed before this instance started is left for the panel's explicit
-	* discard, because it may carry work the switch never saw.
+	* Copies this host instance kept when the switch was turned off, by
+	* repository root. A host restart forgets them; the panel's count then
+	* honestly drops back to leftovers only.
 	*/
-	const createdBySession = /* @__PURE__ */ new Map();
+	const keptCopies = /* @__PURE__ */ new Map();
+	const keep = (root, name) => {
+		const names = keptCopies.get(root) ?? /* @__PURE__ */ new Set();
+		names.add(name);
+		keptCopies.set(root, names);
+	};
+	const forget = (root, name) => {
+		keptCopies.get(root)?.delete(name);
+	};
 	const sessionOf = async (sessionId, signal) => {
 		signal?.throwIfAborted();
 		if (sessionId === "") throw new WorktreeToggleError("bad-request", "a session id is required");
@@ -533,7 +942,7 @@ function createWorktreeToggle(ctx, options) {
 		const current = ctx.workingDirectory.get(agent.session);
 		signal?.throwIfAborted();
 		const sourceDirty = await changedFileCount(ctx, root, signal);
-		const copy = await worktreeAt(current, root);
+		const copy = await worktreeAt(ctx, current, root, signal);
 		options.onScope?.(request.sessionId, copy === null ? null : {
 			worktree: copy,
 			repositoryRoot: root
@@ -567,6 +976,7 @@ function createWorktreeToggle(ctx, options) {
 			repositoryRoot: current.repositoryRoot,
 			workingProject
 		});
+		const base = await resolveBase(ctx, current.repositoryRoot, options.baseRef, signal);
 		let lastFailure;
 		for (let attempt = 0; attempt < CREATE_ATTEMPTS; attempt += 1) {
 			signal?.throwIfAborted();
@@ -574,14 +984,21 @@ function createWorktreeToggle(ctx, options) {
 			try {
 				const created = await ctx.worktrees.create(agent, {
 					name,
-					from: "HEAD"
+					from: base.from
 				}, signal);
 				const worktree = {
 					name: created.branch,
 					path: created.path,
 					branch: created.branch
 				};
-				createdBySession.set(request.sessionId, worktree);
+				const baseCommit = await revParse(ctx, created.path, "HEAD");
+				if (baseCommit !== null) try {
+					await writeOwnership(ctx, created.path, {
+						sessionId: request.sessionId,
+						createdAt: Date.now(),
+						baseCommit
+					});
+				} catch {}
 				options.onScope?.(request.sessionId, {
 					worktree,
 					repositoryRoot: created.repositoryRoot
@@ -590,7 +1007,8 @@ function createWorktreeToggle(ctx, options) {
 					state: "created",
 					worktree,
 					repositoryRoot: created.repositoryRoot,
-					sourceDirty: current.sourceDirty
+					sourceDirty: current.sourceDirty,
+					base: base.base
 				};
 			} catch (error) {
 				lastFailure = error;
@@ -611,6 +1029,22 @@ function createWorktreeToggle(ctx, options) {
 			if (pending.get(request.sessionId) === operation) pending.delete(request.sessionId);
 		}
 	};
+	const scope = async (request, signal) => {
+		const agent = await sessionOf(request.sessionId, signal);
+		const current = ctx.workingDirectory.get(agent.session);
+		const known = options.readScope?.(request.sessionId) ?? null;
+		const found = known !== null && contains(known.worktree.path, current) ? known : await detectSessionScope(ctx, agent, signal);
+		if (found === null) return { inWorktree: false };
+		signal?.throwIfAborted();
+		const changedFiles = await changedFileCount(ctx, found.worktree.path, signal);
+		options.onScope?.(request.sessionId, found);
+		return {
+			inWorktree: true,
+			worktree: found.worktree,
+			repositoryRoot: found.repositoryRoot,
+			changedFiles
+		};
+	};
 	const list = async (request, signal) => {
 		const directory = absolutePath(request.path);
 		let root;
@@ -624,50 +1058,84 @@ function createWorktreeToggle(ctx, options) {
 			throw error;
 		}
 		const records = await listWorktreeRecords(ctx, root, signal);
-		const items = [];
-		for (const record of records) {
-			signal?.throwIfAborted();
-			const path = await canonicalPath(record.path);
-			if (path === root) continue;
-			const name = basename(path);
-			if (!isWorktreeName(name)) continue;
-			const branch = record.branch ?? name;
-			let createdAt = 0;
-			let prunable = true;
-			try {
-				const info = await stat(path);
-				createdAt = Math.trunc(info.birthtimeMs > 0 ? info.birthtimeMs : info.mtimeMs);
-				prunable = false;
-			} catch {}
-			const changedFiles = prunable ? 0 : await changedFileCount(ctx, path, signal);
-			items.push({
-				name,
-				path,
-				branch,
-				createdAt,
-				changedFiles,
-				prunable
-			});
-		}
-		items.sort((left, right) => right.createdAt - left.createdAt || left.name.localeCompare(right.name));
+		const items = await copyItems(ctx, root, records, signal);
+		const orphans = await orphanBranches(ctx, root, records, signal);
+		const kept = keptCopies.get(root);
+		const keptCopiesStillHere = kept === void 0 ? 0 : items.filter((item) => kept.has(item.name)).length;
 		return {
 			supported: true,
 			repositoryRoot: root,
-			items
+			items,
+			orphans,
+			keptCopies: keptCopiesStillHere
 		};
 	};
 	/**
-	* Delete one clean copy and its branch. Both the panel's discard and the
-	* switch's own undo go through here, so the dirty guard has one home.
+	* Delete one branch by name.
+	* @param root - canonical repository root.
+	* @param branch - branch to delete; already validated by the caller.
+	* @param signal - caller cancellation.
+	* @throws {WorktreeToggleError} when Git refused.
+	*/
+	const deleteBranch = async (root, branch, signal) => {
+		const deleted = await runGit(ctx, root, [
+			"branch",
+			"-D",
+			"--",
+			branch
+		], {
+			signal,
+			allowedExitCodes: [0, 1]
+		});
+		const gone = deleted.exitCode === 1 && /not found/i.test(deleted.stderr);
+		if (deleted.exitCode !== 0 && !gone) throw branchDeleteFailure(branch, [
+			"branch",
+			"-D",
+			branch
+		], deleted);
+	};
+	/**
+	* Delete a branch a prunable copy still holds.
+	*
+	* `git branch -D` refuses while any worktree registration names the branch,
+	* even a registration whose directory is gone, so the branch is removed
+	* through the ref itself. The registration still pins Git's bookkeeping, but
+	* nothing can have the branch checked out any more: the directory is missing.
+	* @param root - canonical repository root.
+	* @param branch - branch to delete; already validated by the caller.
+	* @param signal - caller cancellation.
+	* @throws {WorktreeToggleError} when Git refused (for example a locked ref).
+	*/
+	const deleteBranchByRef = async (root, branch, signal) => {
+		const deleted = await runGit(ctx, root, [
+			"update-ref",
+			"-d",
+			`refs/heads/${branch}`
+		], {
+			signal,
+			allowedExitCodes: [0, 1]
+		});
+		if (deleted.exitCode !== 0) throw branchDeleteFailure(branch, [
+			"update-ref",
+			"-d",
+			branch
+		], deleted);
+	};
+	/**
+	* Delete one clean copy and, unless it is detached, its branch.
+	*
+	* Both the panel's discard and the switch's own undo go through here, so the
+	* dirty guard and the delete order have one home. A prunable copy — its
+	* directory was deleted by hand — deletes the branch first and prunes the
+	* registration only once that succeeded, so a refused delete cannot leave the
+	* registration already gone.
 	* @param root - canonical repository root.
 	* @param name - copy name; already validated by the caller.
 	* @param signal - caller cancellation.
 	* @returns the removed copy's identity.
 	*/
 	const removeCopy = async (root, name, signal) => {
-		const listed = await list({ path: root }, signal);
-		if (!listed.supported) throw new WorktreeToggleError("not-a-git-repository", "the project is not inside a Git working tree");
-		const item = listed.items.find((entry) => entry.name === name);
+		const item = (await copyItems(ctx, root, await listWorktreeRecords(ctx, root, signal), signal)).find((entry) => entry.name === name);
 		if (item === void 0) throw new WorktreeToggleError("worktree-not-found", `no worktree named ${name} in ${root}`, {
 			name,
 			repositoryRoot: root
@@ -676,8 +1144,10 @@ function createWorktreeToggle(ctx, options) {
 			name: item.name,
 			changedFiles: item.changedFiles
 		});
-		if (item.prunable) await runGit(ctx, root, ["worktree", "prune"], { signal });
-		else {
+		if (item.prunable) {
+			if (item.branch !== null) await deleteBranchByRef(root, item.branch, signal);
+			await runGit(ctx, root, ["worktree", "prune"], { signal });
+		} else {
 			const removed = await runGit(ctx, root, [
 				"worktree",
 				"remove",
@@ -694,26 +1164,9 @@ function createWorktreeToggle(ctx, options) {
 				name: item.name,
 				path: item.path
 			});
+			if (item.branch !== null) await deleteBranch(root, item.branch, signal);
 		}
-		const deleted = await runGit(ctx, root, [
-			"branch",
-			"-D",
-			"--",
-			item.branch
-		], {
-			signal,
-			allowedExitCodes: [0, 1]
-		});
-		const branchGone = deleted.exitCode === 1 && /not found/i.test(deleted.stderr);
-		if (deleted.exitCode !== 0 && !branchGone) throw new WorktreeToggleError("worktree-remove-failed", new GitFailure([
-			"branch",
-			"-D",
-			item.branch
-		], deleted).message, {
-			name: item.name,
-			branch: item.branch
-		});
-		for (const [sessionId, copy] of createdBySession) if (copy.path === item.path) createdBySession.delete(sessionId);
+		forget(root, item.name);
 		return {
 			removed: true,
 			name: item.name,
@@ -727,6 +1180,17 @@ function createWorktreeToggle(ctx, options) {
 		const root = await repositoryOf(ctx, directory, signal);
 		return await removeCopy(root, request.name, signal);
 	};
+	const discardBranch = async (request, signal) => {
+		const directory = absolutePath(request.path);
+		if (!isGeneratedName(request.branch)) throw new WorktreeToggleError("branch-name-invalid", `not a branch this plugin generated: ${request.branch}`);
+		const root = await repositoryOf(ctx, directory, signal);
+		if ((await listWorktreeRecords(ctx, root, signal)).some((record) => record.branch === request.branch)) throw new WorktreeToggleError("branch-in-use", `${request.branch} is checked out by a worktree; discard that copy instead`, { branch: request.branch });
+		if (new Set((await listBranchRefs(ctx, root, signal)).map((ref) => ref.name)).has(request.branch)) await deleteBranch(root, request.branch, signal);
+		return {
+			removed: true,
+			branch: request.branch
+		};
+	};
 	const release = async (request, signal) => {
 		const running = pending.get(request.sessionId);
 		if (running !== void 0) try {
@@ -743,27 +1207,20 @@ function createWorktreeToggle(ctx, options) {
 			if (error instanceof GitFailure) throw new WorktreeToggleError("not-a-git-repository", "the session project is not inside a Git working tree");
 			throw error;
 		}
-		const listed = await list({ path: anchor }, signal);
-		if (!listed.supported) return {
-			directory: current,
-			removed: null,
-			kept: null
-		};
+		const records = await listWorktreeRecords(ctx, root, signal);
+		const items = await copyItems(ctx, root, records, signal);
 		const path = await canonicalPath(current);
-		const item = listed.items.find((entry) => contains(entry.path, path));
+		const item = items.find((entry) => contains(entry.path, path));
 		if (item === void 0) {
 			options.onScope?.(request.sessionId, null);
 			return {
 				directory: current,
 				removed: null,
-				kept: null
+				kept: null,
+				keptReason: null
 			};
 		}
-		const copy = {
-			name: item.name,
-			path: item.path,
-			branch: item.branch
-		};
+		const copy = copyRef(item);
 		signal?.throwIfAborted();
 		let directory;
 		try {
@@ -775,38 +1232,58 @@ function createWorktreeToggle(ctx, options) {
 			});
 		}
 		options.onScope?.(request.sessionId, null);
-		const mine = createdBySession.get(request.sessionId);
-		if (mine === void 0 || mine.path !== copy.path) return {
-			directory,
-			removed: null,
-			kept: copy
-		};
-		try {
-			const removed = await removeCopy(root, copy.name, signal);
-			return {
+		const keepCopy = (reason, error) => {
+			keep(root, item.name);
+			return error === void 0 ? {
 				directory,
-				removed: {
-					name: removed.name,
-					path: removed.path,
-					branch: removed.branch
-				},
-				kept: null
-			};
-		} catch (error) {
-			if (signal?.aborted === true) throw error;
-			return {
+				removed: null,
+				kept: copy,
+				keptReason: reason
+			} : {
 				directory,
 				removed: null,
-				kept: copy
+				kept: copy,
+				keptReason: reason,
+				error
 			};
+		};
+		const ownership = await readOwnership(ctx, item.path, signal);
+		if (ownership === null || ownership.sessionId !== request.sessionId) return keepCopy("not-owned");
+		if (item.changedFiles > 0) return keepCopy("dirty", `${item.changedFiles} uncommitted change(s)`);
+		const tip = await revParse(ctx, item.path, "HEAD", signal);
+		if (tip === null || tip !== ownership.baseCommit) {
+			let commits = 0;
+			try {
+				commits = await revListCount(ctx, item.path, `${ownership.baseCommit}..HEAD`, signal);
+			} catch {}
+			return keepCopy("dirty", `${commits} new commit(s)`);
 		}
+		let removed;
+		try {
+			removed = await removeCopy(root, item.name, signal);
+		} catch (error) {
+			keep(root, item.name);
+			throw error;
+		}
+		return {
+			directory,
+			removed: {
+				name: removed.name,
+				path: removed.path,
+				branch: removed.branch
+			},
+			kept: null,
+			keptReason: null
+		};
 	};
 	return {
 		status,
 		prepare,
 		release,
+		scope,
 		list,
-		discard
+		discard,
+		discardBranch
 	};
 }
 // src/host/routes.ts
@@ -819,8 +1296,10 @@ const ENDPOINTS = [
 	"status",
 	"prepare",
 	"release",
+	"scope",
 	"list",
-	"discard"
+	"discard",
+	"discardBranch"
 ];
 /** A payload object with the named string field, or the failure to send back. */
 function requiredString(payload, field) {
@@ -890,6 +1369,11 @@ async function dispatch(toggle, endpoint, payload, signal) {
 			if ("failure" in sessionId) throw sessionId.failure;
 			return ok(await toggle.release({ sessionId: sessionId.value }, signal));
 		}
+		if (endpoint === "scope") {
+			const sessionId = requiredString(payload, "sessionId");
+			if ("failure" in sessionId) throw sessionId.failure;
+			return ok(await toggle.scope({ sessionId: sessionId.value }, signal));
+		}
 		if (endpoint === "list") {
 			const path = requiredString(payload, "path");
 			if ("failure" in path) throw path.failure;
@@ -897,6 +1381,14 @@ async function dispatch(toggle, endpoint, payload, signal) {
 		}
 		const path = requiredString(payload, "path");
 		if ("failure" in path) throw path.failure;
+		if (endpoint === "discardBranch") {
+			const branch = requiredString(payload, "branch");
+			if ("failure" in branch) throw branch.failure;
+			return ok(await toggle.discardBranch({
+				path: path.value,
+				branch: branch.value
+			}, signal));
+		}
 		const name = requiredString(payload, "name");
 		if ("failure" in name) throw name.failure;
 		return ok(await toggle.discard({
@@ -1063,7 +1555,8 @@ const inject = [
 /** Schemastery schema for {@link Config}. */
 const Config = Schema.object({
 	defaultEnabled: Schema.boolean().default(true).description("Start a new session in a worktree copy until the user turns the switch off for that project."),
-	guardSourceCheckout: Schema.boolean().default(true).description("While a session is in a copy, deny shell commands that run Git against the project checkout.")
+	guardSourceCheckout: Schema.boolean().default(true).description("While a session is in a copy, deny shell commands that run Git against the project checkout."),
+	baseRef: Schema.union([Schema.const("fresh"), Schema.const("head")]).default("fresh").description("Where a new copy starts: 'fresh' fetches origin's default branch first; 'head' starts at local HEAD without network access.")
 });
 /**
 * Mount the host half.
@@ -1074,10 +1567,12 @@ function apply(ctx, config) {
 	const scopes = new SessionScopeRegistry();
 	const toggle = createWorktreeToggle(ctx, {
 		defaultEnabled: config.defaultEnabled,
+		baseRef: config.baseRef,
 		onScope: (sessionId, scope) => {
 			if (scope === null) scopes.forget(sessionId);
 			else scopes.remember(sessionId, scope);
-		}
+		},
+		readScope: (sessionId) => scopes.get(sessionId)
 	});
 	installWorktreeScope(ctx, {
 		registry: scopes,