dsh-worktree-switch 0.0.0-stage → 0.3.0

package/lib/index.js

@@ -0,0 +1,1091 @@
+import Schema from "@deepseek-ai/schemastery";
+import { basename, dirname, isAbsolute, relative, resolve } from "node:path";
+import { lstat, realpath, stat } from "node:fs/promises";
+// src/host/paths.ts
+/**
+* Path predicates the host half shares between the verbs, the scope hint, and
+* the working-directory watcher.
+* @module dsh-worktree-switch/host/paths
+*/
+/**
+* Whether one absolute directory is the path itself or an ancestor of it.
+* @param directory - candidate ancestor.
+* @param path - absolute path to test.
+* @returns true when `path` is `directory` or lives below it.
+*/
+function contains(directory, path) {
+	const inside = relative(directory, path);
+	return inside === "" || !inside.startsWith("..") && !isAbsolute(inside);
+}
+// src/host/guard.ts
+/**
+* The source-checkout guard: while a session runs in a worktree copy, shell
+* commands that would run Git against the project checkout are refused before
+* dispatch.
+*
+* The prompt context (`worktree-switch:scope`) explains where the workspace
+* is, but it cannot stop a model that still reaches for the checkout it can
+* see — and the sandbox deliberately grants writes there. This guard is the
+* enforcement half that needs no harness change: `tools/pre-execute` can deny
+* one call, and the model reads the reason as that call's error result.
+*
+* The pattern is deliberately narrow. Only a shell call that mentions `git`
+* is considered, and only when it names the project checkout either as an
+* explicit `workdir` or as a literal absolute path in the command text.
+* `cd ..`-style relative escapes and shell variables are not resolved; the
+* guard is a net, not the sandbox boundary.
+* @module dsh-worktree-switch/host/guard
+*/
+/** Tool names whose `command` argument is executed by a shell. */
+const SHELL_TOOLS = /* @__PURE__ */ new Set(["bash"]);
+/**
+* Read a shell call's command and explicit directory, if this is one.
+* @param exec - the pending tool call.
+* @returns the fields the guard needs, or null for every other tool.
+*/
+function shellArguments(exec) {
+	if (!SHELL_TOOLS.has(exec.name)) return null;
+	if (exec.arguments === null || typeof exec.arguments !== "object") return null;
+	const args = exec.arguments;
+	const command = args["command"];
+	if (typeof command !== "string" || command.trim() === "") return null;
+	const workdir = args["workdir"];
+	const explicit = typeof workdir === "string" && workdir.trim() !== "" ? workdir : void 0;
+	return explicit === void 0 ? { command } : {
+		command,
+		workdir: explicit
+	};
+}
+/**
+* The model-facing denial for one shell command.
+* @param command - shell command text as the model wrote it.
+* @param workdir - explicit working directory, when the call carried one.
+* @param cwd - the session's committed working directory.
+* @param scope - the copy the session runs in.
+* @returns the denial reason, or null when the call may run.
+*/
+function sourceCheckoutDenial(command, workdir, cwd, scope) {
+	if (!/\bgit\b/.test(command)) return null;
+	const checkout = scope.worktree.path;
+	const project = scope.repositoryRoot;
+	if (workdir !== void 0) {
+		const target = isAbsolute(workdir) ? workdir : resolve(cwd, workdir);
+		if (contains(project, target) && !contains(checkout, target)) return denial(scope);
+	}
+	if (command.split(checkout).join("").includes(project)) return denial(scope);
+	return null;
+}
+/** The one explanation every denial carries, including the way to get main. */
+function denial(scope) {
+	return `Denied: this session runs in the worktree copy ${JSON.stringify(scope.worktree.path)}, so Git commands targeting the project checkout ${JSON.stringify(scope.repositoryRoot)} are blocked. Run Git in the current working directory instead; to bring main's latest into this copy, use \`git fetch origin main\` and then \`git merge origin/main\` (or \`git rebase origin/main\`).`;
+}
+/**
+* Refuse shell calls that run Git against the project checkout while the
+* session is inside a copy.
+*
+* The registry is the same one the prompt context reads, so the guard is
+* active exactly while the model has been told it is in a copy.
+* @param ctx - host context carrying `workingDirectory` and the tool runtime.
+* @param registry - sessions' confirmed copies.
+*/
+function installSourceCheckoutGuard(ctx, registry) {
+	ctx.on("tools/pre-execute", async (exec, next) => {
+		const agent = exec.agent;
+		if (agent === void 0) return next();
+		const scope = registry.get(String(agent.session.id));
+		if (scope === null) return next();
+		const args = shellArguments(exec);
+		if (args === null) return next();
+		const denial = sourceCheckoutDenial(args.command, args.workdir, ctx.workingDirectory.get(agent.session), scope);
+		return denial === null ? next() : {
+			kind: "deny",
+			reason: denial
+		};
+	});
+}
+/** Per-stream capture cap; worktree listings and status lines are small. */
+const MAX_OUTPUT_BYTES = 1048576;
+/**
+* Clear inherited repository selectors and config so the command reads the
+* checkout named by `cwd`, never one inherited from the Host's environment.
+* One entry per key: `undefined` removes the variable for the child.
+*/
+const GIT_ENV = Object.fromEntries([
+	"GIT_DIR",
+	"GIT_WORK_TREE",
+	"GIT_COMMON_DIR",
+	"GIT_INDEX_FILE",
+	"GIT_OBJECT_DIRECTORY",
+	"GIT_ALTERNATE_OBJECT_DIRECTORIES",
+	"GIT_CONFIG",
+	"GIT_CONFIG_PARAMETERS",
+	"GIT_CONFIG_COUNT",
+	"GIT_CEILING_DIRECTORIES",
+	"GIT_PREFIX",
+	"GIT_SHALLOW_FILE",
+	"GIT_GRAFT_FILE",
+	"GIT_REPLACE_REF_BASE",
+	"GIT_ATTR_SOURCE"
+].map((key) => [key, void 0]));
+/** A Git invocation that exited with a status the caller did not allow. */
+var GitFailure = class extends Error {
+	args;
+	result;
+	/**
+	* @param args - arguments after the executable, for diagnostics.
+	* @param result - the captured outcome.
+	*/
+	constructor(args, result) {
+		const detail = result.stderr.trim() === "" ? result.stdout.trim() : result.stderr.trim();
+		super(`git ${args.join(" ")} failed (exit ${result.exitCode})${detail === "" ? "" : `: ${detail}`}`);
+		this.args = args;
+		this.result = result;
+		this.name = "GitFailure";
+	}
+};
+/**
+* Run one Git command without a shell and await its termination.
+* @param ctx - Host context carrying the subprocess provider.
+* @param cwd - absolute directory the command runs in.
+* @param args - arguments after the executable.
+* @param options - cancellation, accepted exit statuses, and deadline.
+* @returns captured stdout, stderr, and exit status.
+* @throws {GitFailure} when the exit status is not allowed or the command was killed.
+*/
+async function runGit(ctx, cwd, args, options = {}) {
+	const deadline = AbortSignal.timeout(options.timeoutMs ?? 2e4);
+	const signal = options.signal === void 0 ? deadline : AbortSignal.any([options.signal, deadline]);
+	const allowed = options.allowedExitCodes ?? [0];
+	const argv = [
+		await ctx.subprocess.resolveExecutable("git", void 0, signal),
+		"-c",
+		"core.hooksPath=/dev/null",
+		"-c",
+		"core.fsmonitor=false",
+		...args
+	];
+	const child = ctx.subprocess.spawn({
+		argv,
+		cwd,
+		env: {
+			...GIT_ENV,
+			GIT_TERMINAL_PROMPT: "0",
+			GIT_LFS_SKIP_SMUDGE: "1",
+			GIT_NO_LAZY_FETCH: "1"
+		},
+		signal,
+		graceMs: 1500,
+		stdio: {
+			stdin: "ignore",
+			stdout: { maxBytes: MAX_OUTPUT_BYTES },
+			stderr: { maxBytes: MAX_OUTPUT_BYTES }
+		}
+	});
+	try {
+		const outcome = await child.done;
+		const result = {
+			stdout: child.collected.stdout?.readFrom(0).text ?? "",
+			stderr: child.collected.stderr?.readFrom(0).text ?? "",
+			exitCode: outcome.exitCode ?? -1
+		};
+		if (outcome.exitCode === null || !allowed.includes(outcome.exitCode)) throw new GitFailure(args, result);
+		return result;
+	} finally {
+		child.terminate();
+		await child.waitForExit();
+	}
+}
+/**
+* Resolve the repository root that contains `directory`.
+* @param ctx - Host context carrying the subprocess provider.
+* @param directory - absolute directory inside (or at) the checkout.
+* @param signal - caller cancellation.
+* @returns the canonical top-level directory Git reports.
+* @throws {GitFailure} when the directory is not inside a Git working tree.
+*/
+async function repositoryRoot(ctx, directory, signal) {
+	const result = await runGit(ctx, directory, ["rev-parse", "--show-toplevel"], {
+		signal,
+		allowedExitCodes: [0, 128]
+	});
+	if (result.exitCode !== 0) throw new GitFailure(["rev-parse", "--show-toplevel"], result);
+	return result.stdout.replace(/\r?\n$/, "");
+}
+/**
+* Resolve symlinks in a path that exists, falling back to the path as given.
+* @param path - absolute path.
+* @returns the canonical spelling when the path exists.
+*/
+async function canonicalPath(path) {
+	try {
+		return await realpath(path);
+	} catch {
+		return path;
+	}
+}
+/**
+* Parse `git worktree list --porcelain` output into its records.
+* @param stdout - the command's stdout.
+* @returns one record per reported checkout, in Git's order.
+*/
+function parseWorktreeList(stdout) {
+	const records = [];
+	let path;
+	let branch;
+	const flush = () => {
+		if (path === void 0) return;
+		records.push(branch === void 0 ? { path } : {
+			path,
+			branch
+		});
+		path = void 0;
+		branch = void 0;
+	};
+	for (const line of stdout.split("\n")) {
+		if (line === "") {
+			flush();
+			continue;
+		}
+		if (line.startsWith("worktree ")) path = line.slice(9);
+		else if (line.startsWith("branch refs/heads/")) branch = line.slice(18);
+	}
+	flush();
+	return records;
+}
+/**
+* List the worktree checkouts 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 checkout Git reports for the repository.
+*/
+async function listWorktreeRecords(ctx, root, signal) {
+	return parseWorktreeList((await runGit(ctx, root, [
+		"worktree",
+		"list",
+		"--porcelain"
+	], { signal })).stdout);
+}
+/**
+* Count the changed and untracked files of one checkout.
+* @param ctx - Host context carrying the subprocess provider.
+* @param directory - checkout directory to inspect.
+* @param signal - caller cancellation.
+* @returns the number of `git status --porcelain` entries.
+*/
+async function changedFileCount(ctx, directory, signal) {
+	return (await runGit(ctx, directory, [
+		"status",
+		"--porcelain",
+		"--untracked-files=normal"
+	], { signal })).stdout.split("\n").filter((line) => line.trim() !== "").length;
+}
+// src/host/naming.ts
+/**
+* Names for the copy a session gets: lowercase words and a short suffix, so a
+* branch, a directory, a `git branch` row and this plugin's UI all read the
+* same. No prefix: the pool path already says where it lives.
+* @module dsh-worktree-switch/host/naming
+*/
+/** First word of a generated name. */
+const ADJECTIVES = [
+	"amber",
+	"brisk",
+	"calm",
+	"clever",
+	"crisp",
+	"eager",
+	"faint",
+	"fresh",
+	"gentle",
+	"happy",
+	"hollow",
+	"kind",
+	"lively",
+	"mellow",
+	"nimble",
+	"polite",
+	"quiet",
+	"rapid",
+	"ready",
+	"silent",
+	"soft",
+	"solid",
+	"steady",
+	"sunny",
+	"swift",
+	"tidy",
+	"vivid",
+	"warm",
+	"wise",
+	"young"
+];
+/** Second word of a generated name. */
+const NOUNS = [
+	"anchor",
+	"atlas",
+	"badger",
+	"birch",
+	"brook",
+	"cedar",
+	"comet",
+	"coral",
+	"delta",
+	"ember",
+	"fern",
+	"field",
+	"finch",
+	"glade",
+	"harbor",
+	"heron",
+	"island",
+	"lark",
+	"ledge",
+	"maple",
+	"meadow",
+	"otter",
+	"pebble",
+	"pine",
+	"quartz",
+	"river",
+	"shore",
+	"stone",
+	"trail",
+	"willow"
+];
+/**
+* Generate one candidate worktree name.
+* @param random - uniform source in `[0, 1)`; injectable for deterministic tests.
+* @returns a lowercase, hyphen-joined branch-safe name such as `quiet-harbor-3fa9`.
+*/
+function worktreeName(random = Math.random) {
+	const pick = (values) => {
+		return values[Math.min(values.length - 1, Math.floor(random() * values.length))] ?? values[0] ?? "copy";
+	};
+	const suffix = Math.min(65535, Math.floor(random() * 65536)).toString(16).padStart(4, "0");
+	return `${pick(ADJECTIVES)}-${pick(NOUNS)}-${suffix}`;
+}
+/** 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._-]*$/;
+/**
+* Validate a worktree name received from the browser before it reaches Git.
+* @param value - candidate name.
+* @returns true for one plain path segment that Git also accepts as a branch.
+*/
+function isWorktreeName(value) {
+	return NAME_PATTERN.test(value) && !value.endsWith(".lock");
+}
+// src/host/handlers.ts
+/**
+* The plugin's host Remote face: the five 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 —
+* Git, the worktree service, the sandbox policy it applies, and session
+* working-directory publication — belongs to the harness and is exercised by
+* its own tests.
+* @module dsh-worktree-switch/host/handlers
+*/
+/** Attempts at a fresh name before a creation failure becomes an error. */
+const CREATE_ATTEMPTS = 3;
+/** A failed verb, carrying the stable code the browser half switches on. */
+var WorktreeToggleError = class extends Error {
+	code;
+	details;
+	/**
+	* @param code - stable failure code.
+	* @param message - human-readable explanation.
+	* @param details - extra machine-readable facts.
+	*/
+	constructor(code, message, details = {}) {
+		super(message);
+		this.code = code;
+		this.details = details;
+		this.name = "WorktreeToggleError";
+	}
+};
+/** Normalize a browser-supplied path before any filesystem work. */
+function absolutePath(value) {
+	const trimmed = value.trim();
+	if (trimmed === "") throw new WorktreeToggleError("bad-request", "a project path is required");
+	return resolve(trimmed);
+}
+/**
+* The copy a session already runs in.
+*
+* A linked worktree is recognised from the checkout itself — its `.git` is a
+* file pointing back at the source repository, not a directory — rather than
+* 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 current - the session's committed working directory.
+* @param repositoryRoot - canonical root of the project's repository.
+* @returns the copy's identity, or null when the directory is not one.
+*/
+async function worktreeAt(current, repositoryRoot) {
+	const path = await canonicalPath(current);
+	if (path === repositoryRoot) return null;
+	const inside = relative(repositoryRoot, path);
+	if (inside === "" || inside.startsWith("..") || isAbsolute(inside)) return null;
+	const name = basename(path);
+	if (!isWorktreeName(name)) return null;
+	try {
+		if (!(await lstat(`${path}/.git`)).isFile()) return null;
+	} catch {
+		return null;
+	}
+	return {
+		name,
+		path,
+		branch: name
+	};
+}
+/**
+* Resolve the canonical root of the repository that contains a directory.
+* Git reports the spelling of the path it was given; the worktree service
+* publishes canonical paths, so both halves must agree on one spelling.
+* @param ctx - host context carrying `subprocess`.
+* @param directory - absolute directory inside the project.
+* @param signal - caller cancellation.
+* @returns the canonical repository root.
+*/
+async function repositoryOf(ctx, directory, signal) {
+	return canonicalPath(await repositoryRoot(ctx, directory, signal));
+}
+/**
+* Re-derive the copy one session runs in from its committed directory.
+*
+* A copy's root is the only linked checkout whose name matches the pool
+* convention, but a session may have changed into a directory *inside* the copy,
+* so ancestors are probed from the committed directory up to the project
+* anchor.
+* @param ctx - host context carrying `workingDirectory` and `subprocess`.
+* @param agent - live session owner.
+* @param signal - caller cancellation.
+* @returns the copy and project root, or null when the session is not in one.
+*/
+async function detectSessionScope(ctx, agent, signal) {
+	const current = ctx.workingDirectory.get(agent.session);
+	const anchor = agent.session.header.cwd ?? current;
+	if (current === anchor || !contains(anchor, current)) return null;
+	let root;
+	try {
+		root = await repositoryOf(ctx, anchor, signal);
+	} catch {
+		return null;
+	}
+	signal?.throwIfAborted();
+	let probe = current;
+	for (;;) {
+		const copy = await worktreeAt(probe, root);
+		if (copy !== null) return {
+			worktree: copy,
+			repositoryRoot: root
+		};
+		const parent = dirname(probe);
+		if (probe === root || probe === anchor || parent === probe) return null;
+		probe = parent;
+	}
+}
+/**
+* Build the host face.
+* @param ctx - Host context with `agents`, `worktrees`, `workingDirectory`, and `subprocess`.
+* @param options - resolved row config.
+* @returns the five verbs.
+*/
+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.
+	*/
+	const createdBySession = /* @__PURE__ */ new Map();
+	const sessionOf = async (sessionId, signal) => {
+		signal?.throwIfAborted();
+		if (sessionId === "") throw new WorktreeToggleError("bad-request", "a session id is required");
+		const controller = ctx.get("sessionController");
+		if (controller !== void 0) {
+			const resolved = await controller.resolveAgent(sessionId);
+			if ("error" in resolved) throw new WorktreeToggleError(resolved.error.code, resolved.error.message, { sessionId });
+			return resolved.agent;
+		}
+		const agent = ctx.agents.get(sessionId);
+		if (agent === void 0) throw new WorktreeToggleError("session-not-found", `no live agent for session ${sessionId}`, { sessionId });
+		return agent;
+	};
+	const status = async (request, signal) => {
+		const agent = await sessionOf(request.sessionId, signal);
+		const startDirectory = agent.session.header.cwd ?? ctx.workingDirectory.get(agent.session);
+		let root;
+		try {
+			root = await repositoryOf(ctx, startDirectory, signal);
+		} catch (error) {
+			if (error instanceof GitFailure) return {
+				supported: false,
+				reason: "not-a-git-repository",
+				defaultEnabled: options.defaultEnabled
+			};
+			throw error;
+		}
+		const current = ctx.workingDirectory.get(agent.session);
+		signal?.throwIfAborted();
+		const sourceDirty = await changedFileCount(ctx, root, signal);
+		const copy = await worktreeAt(current, root);
+		options.onScope?.(request.sessionId, copy === null ? null : {
+			worktree: copy,
+			repositoryRoot: root
+		});
+		return {
+			supported: true,
+			repositoryRoot: root,
+			sessionWorktree: copy,
+			sourceDirty,
+			defaultEnabled: options.defaultEnabled
+		};
+	};
+	const prepareOnce = async (request, signal) => {
+		const agent = await sessionOf(request.sessionId, signal);
+		const current = await status(request, signal);
+		if (!current.supported) throw new WorktreeToggleError("not-a-git-repository", "the session project is not inside a Git working tree");
+		if (current.sessionWorktree !== null) {
+			options.onScope?.(request.sessionId, {
+				worktree: current.sessionWorktree,
+				repositoryRoot: current.repositoryRoot
+			});
+			return {
+				state: "existing",
+				worktree: current.sessionWorktree,
+				repositoryRoot: current.repositoryRoot,
+				sourceDirty: current.sourceDirty
+			};
+		}
+		const workingProject = await repositoryOf(ctx, ctx.workingDirectory.get(agent.session), signal);
+		if (workingProject !== current.repositoryRoot) throw new WorktreeToggleError("session-moved", `this session now works in ${workingProject}, not in its project ${current.repositoryRoot}`, {
+			repositoryRoot: current.repositoryRoot,
+			workingProject
+		});
+		let lastFailure;
+		for (let attempt = 0; attempt < CREATE_ATTEMPTS; attempt += 1) {
+			signal?.throwIfAborted();
+			const name = worktreeName();
+			try {
+				const created = await ctx.worktrees.create(agent, {
+					name,
+					from: "HEAD"
+				}, signal);
+				const worktree = {
+					name: created.branch,
+					path: created.path,
+					branch: created.branch
+				};
+				createdBySession.set(request.sessionId, worktree);
+				options.onScope?.(request.sessionId, {
+					worktree,
+					repositoryRoot: created.repositoryRoot
+				});
+				return {
+					state: "created",
+					worktree,
+					repositoryRoot: created.repositoryRoot,
+					sourceDirty: current.sourceDirty
+				};
+			} catch (error) {
+				lastFailure = error;
+				const message = error instanceof Error ? error.message : String(error);
+				if (!/already exists|worktree branch already exists|worktree path already exists/i.test(message)) throw new WorktreeToggleError("worktree-create-failed", message, { name });
+			}
+		}
+		throw new WorktreeToggleError("worktree-create-failed", `could not allocate a free worktree name after ${CREATE_ATTEMPTS} attempts`, { cause: lastFailure instanceof Error ? lastFailure.message : String(lastFailure) });
+	};
+	const prepare = async (request, signal) => {
+		const running = pending.get(request.sessionId);
+		if (running !== void 0) return running;
+		const operation = prepareOnce(request, signal);
+		pending.set(request.sessionId, operation);
+		try {
+			return await operation;
+		} finally {
+			if (pending.get(request.sessionId) === operation) pending.delete(request.sessionId);
+		}
+	};
+	const list = async (request, signal) => {
+		const directory = absolutePath(request.path);
+		let root;
+		try {
+			root = await repositoryOf(ctx, directory, signal);
+		} catch (error) {
+			if (error instanceof GitFailure) return {
+				supported: false,
+				reason: "not-a-git-repository"
+			};
+			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));
+		return {
+			supported: true,
+			repositoryRoot: root,
+			items
+		};
+	};
+	/**
+	* 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.
+	* @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);
+		if (item === void 0) throw new WorktreeToggleError("worktree-not-found", `no worktree named ${name} in ${root}`, {
+			name,
+			repositoryRoot: root
+		});
+		if (item.changedFiles > 0) throw new WorktreeToggleError("worktree-dirty", `${item.name} has ${item.changedFiles} uncommitted change(s); commit or discard them first`, {
+			name: item.name,
+			changedFiles: item.changedFiles
+		});
+		if (item.prunable) await runGit(ctx, root, ["worktree", "prune"], { signal });
+		else {
+			const removed = await runGit(ctx, root, [
+				"worktree",
+				"remove",
+				item.path
+			], {
+				signal,
+				allowedExitCodes: [0, 128]
+			});
+			if (removed.exitCode !== 0) throw new WorktreeToggleError("worktree-remove-failed", new GitFailure([
+				"worktree",
+				"remove",
+				item.path
+			], removed).message, {
+				name: item.name,
+				path: item.path
+			});
+		}
+		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);
+		return {
+			removed: true,
+			name: item.name,
+			branch: item.branch,
+			path: item.path
+		};
+	};
+	const discard = async (request, signal) => {
+		const directory = absolutePath(request.path);
+		if (!isWorktreeName(request.name)) throw new WorktreeToggleError("worktree-name-invalid", `not a worktree name: ${request.name}`);
+		const root = await repositoryOf(ctx, directory, signal);
+		return await removeCopy(root, request.name, signal);
+	};
+	const release = async (request, signal) => {
+		const running = pending.get(request.sessionId);
+		if (running !== void 0) try {
+			await running;
+		} catch {}
+		signal?.throwIfAborted();
+		const agent = await sessionOf(request.sessionId, signal);
+		const current = ctx.workingDirectory.get(agent.session);
+		const anchor = agent.session.header.cwd ?? current;
+		let root;
+		try {
+			root = await repositoryOf(ctx, anchor, signal);
+		} catch (error) {
+			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 path = await canonicalPath(current);
+		const item = listed.items.find((entry) => contains(entry.path, path));
+		if (item === void 0) {
+			options.onScope?.(request.sessionId, null);
+			return {
+				directory: current,
+				removed: null,
+				kept: null
+			};
+		}
+		const copy = {
+			name: item.name,
+			path: item.path,
+			branch: item.branch
+		};
+		signal?.throwIfAborted();
+		let directory;
+		try {
+			directory = await ctx.workingDirectory.set(agent, anchor, signal);
+		} catch (error) {
+			throw new WorktreeToggleError("release-failed", `could not move the session back to ${anchor}: ${error instanceof Error ? error.message : String(error)}`, {
+				name: copy.name,
+				path: copy.path
+			});
+		}
+		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 {
+				directory,
+				removed: {
+					name: removed.name,
+					path: removed.path,
+					branch: removed.branch
+				},
+				kept: null
+			};
+		} catch (error) {
+			if (signal?.aborted === true) throw error;
+			return {
+				directory,
+				removed: null,
+				kept: copy
+			};
+		}
+	};
+	return {
+		status,
+		prepare,
+		release,
+		list,
+		discard
+	};
+}
+// src/host/routes.ts
+/** Absolute prefix every route below lives under. */
+const API_PREFIX = "/api/dsh-worktree-switch";
+/** Plugin id; the wire method prefix and the package name are the same string. */
+const PLUGIN_ID = "dsh-worktree-switch";
+/** One route per verb. */
+const ENDPOINTS = [
+	"status",
+	"prepare",
+	"release",
+	"list",
+	"discard"
+];
+/** A payload object with the named string field, or the failure to send back. */
+function requiredString(payload, field) {
+	const value = payload[field];
+	if (typeof value !== "string" || value.trim() === "") return { failure: new WorktreeToggleError("bad-request", `payload.${field} must be a non-empty string`) };
+	return { value };
+}
+/**
+* Decode the browser's `client-request` envelope.
+* @param body - parsed JSON body.
+* @returns the request, or null when the envelope is malformed.
+*/
+function readClientRequest(body) {
+	if (body === null || typeof body !== "object" || Array.isArray(body)) return null;
+	const record = body;
+	if (record.type !== "client-request") return null;
+	const { rpcId, method } = record;
+	if (typeof rpcId !== "string" || rpcId === "") return null;
+	if (typeof method !== "string" || method === "") return null;
+	const payload = record.payload;
+	return {
+		rpcId,
+		method,
+		payload: payload !== null && typeof payload === "object" && !Array.isArray(payload) ? payload : {}
+	};
+}
+/** A successful result. */
+function ok(value) {
+	return {
+		ok: true,
+		value
+	};
+}
+/** A failed result carrying the stable code. */
+function fail(code, message, details = {}) {
+	return {
+		ok: false,
+		error: {
+			code,
+			message,
+			details
+		}
+	};
+}
+/**
+* Dispatch one decoded verb.
+* @param toggle - the host face.
+* @param endpoint - the verb.
+* @param payload - its decoded payload.
+* @param signal - request cancellation.
+* @returns the wire result.
+*/
+async function dispatch(toggle, endpoint, payload, signal) {
+	try {
+		if (endpoint === "status") {
+			const sessionId = requiredString(payload, "sessionId");
+			if ("failure" in sessionId) throw sessionId.failure;
+			return ok(await toggle.status({ sessionId: sessionId.value }, signal));
+		}
+		if (endpoint === "prepare") {
+			const sessionId = requiredString(payload, "sessionId");
+			if ("failure" in sessionId) throw sessionId.failure;
+			return ok(await toggle.prepare({ sessionId: sessionId.value }, signal));
+		}
+		if (endpoint === "release") {
+			const sessionId = requiredString(payload, "sessionId");
+			if ("failure" in sessionId) throw sessionId.failure;
+			return ok(await toggle.release({ sessionId: sessionId.value }, signal));
+		}
+		if (endpoint === "list") {
+			const path = requiredString(payload, "path");
+			if ("failure" in path) throw path.failure;
+			return ok(await toggle.list({ path: path.value }, signal));
+		}
+		const path = requiredString(payload, "path");
+		if ("failure" in path) throw path.failure;
+		const name = requiredString(payload, "name");
+		if ("failure" in name) throw name.failure;
+		return ok(await toggle.discard({
+			path: path.value,
+			name: name.value
+		}, signal));
+	} catch (error) {
+		if (error instanceof WorktreeToggleError) return fail(error.code, error.message, { ...error.details });
+		return fail("internal", error instanceof Error ? error.message : String(error));
+	}
+}
+/**
+* Register one exact route per verb on the shared `/api` channel.
+* @param ctx - Host context carrying `connection`.
+* @param toggle - the host face the routes call.
+*/
+function registerWorktreeRoutes(ctx, toggle) {
+	for (const endpoint of ENDPOINTS) ctx.effect(() => ctx.connection.fetch.register({
+		path: `${API_PREFIX}/${endpoint}`,
+		methods: ["POST"],
+		requestBody: "buffered",
+		async fetch(request) {
+			if (request.headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase() !== "application/json") return new Response("content type must be application/json", { status: 415 });
+			let body;
+			try {
+				body = await request.json();
+			} catch {
+				return new Response("body is not JSON", { status: 400 });
+			}
+			const message = readClientRequest(body);
+			if (message === null) return new Response("invalid client-request message", { status: 400 });
+			if (message.method !== `dsh-worktree-switch/${endpoint}`) return Response.json({
+				type: "server-response",
+				rpcId: message.rpcId,
+				result: fail("bad-request", "RPC method does not match endpoint")
+			});
+			const result = await dispatch(toggle, endpoint, message.payload, request.signal);
+			return Response.json({
+				type: "server-response",
+				rpcId: message.rpcId,
+				result
+			});
+		}
+	}), `${PLUGIN_ID} ${endpoint} route`);
+}
+// src/host/scope.ts
+/** Sessions whose confirmed copy the prompt context reads. */
+var SessionScopeRegistry = class {
+	scopes = /* @__PURE__ */ new Map();
+	/**
+	* Read one session's confirmed scope, without any filesystem work.
+	* @param sessionId - wire session identity.
+	* @returns the known copy, or null.
+	*/
+	get(sessionId) {
+		return this.scopes.get(sessionId) ?? null;
+	}
+	/**
+	* Record that a session now runs in a copy.
+	* @param sessionId - wire session identity.
+	* @param scope - the confirmed copy and its project root.
+	*/
+	remember(sessionId, scope) {
+		this.scopes.set(sessionId, scope);
+	}
+	/**
+	* Drop a session's scope; a session with no entry gets no hint.
+	* @param sessionId - wire session identity.
+	*/
+	forget(sessionId) {
+		this.scopes.delete(sessionId);
+	}
+	/** Drop every entry; the plugin dropping its context drops its hints with it. */
+	clear() {
+		this.scopes.clear();
+	}
+};
+/**
+* The model-facing line describing a worktree session's workspace.
+* @param scope - the session's confirmed copy.
+* @returns one sentence pair, JSON-quoted so paths survive the prompt.
+*/
+function scopeHint(scope) {
+	return `This session is a linked Git worktree checkout at ${JSON.stringify(scope.worktree.path)} of the project ${JSON.stringify(scope.repositoryRoot)}. Run Git commands and file edits from the current working directory; the project checkout is the source, not this session's workspace.`;
+}
+/**
+* Register the worktree scope as dynamic prompt context and keep it fresh.
+*
+* The context is `required`, so it survives compositions that suppress
+* optional runtime context, and it renders from the registry synchronously —
+* the expensive Git detection happens on session creation and directory
+* changes, never at request time.
+* @param ctx - host context carrying `systemPrompt`, `agents`, and `workingDirectory`.
+* @param wiring - registry plus the Git-backed detector.
+*/
+function installWorktreeScope(ctx, wiring) {
+	const { registry, detect } = wiring;
+	ctx.inject(["systemPrompt"], (scoped) => {
+		scoped.systemPrompt.context({
+			name: "worktree-switch:scope",
+			order: scoped.systemPrompt.getContextOrder("WORKING_DIRECTORY") + 5,
+			interpolate: false,
+			required: true,
+			text: (assembly) => {
+				const agent = assembly.agent;
+				if (agent === void 0) return "";
+				const sessionId = String(agent.session.id);
+				const current = ctx.workingDirectory.get(agent.session);
+				const scope = registry.get(sessionId);
+				if (scope !== null && contains(scope.worktree.path, current)) return scopeHint(scope);
+				if (scope !== null) registry.forget(sessionId);
+				const anchor = agent.session.header.cwd ?? current;
+				if (current === anchor || !contains(anchor, current)) return "";
+				if (lastChecked.get(sessionId) === current) return "";
+				refresh(agent, current);
+				return "";
+			}
+		});
+	});
+	const inFlight = /* @__PURE__ */ new Set();
+	/** The directory value each session was last inspected at, hit or miss. */
+	const lastChecked = /* @__PURE__ */ new Map();
+	/** Re-derive one live agent's scope, remembering or forgetting it. */
+	const refresh = async (agent, current = ctx.workingDirectory.get(agent.session)) => {
+		const sessionId = String(agent.session.id);
+		const anchor = agent.session.header.cwd ?? current;
+		if (current === anchor || !contains(anchor, current)) {
+			registry.forget(sessionId);
+			return;
+		}
+		if (inFlight.has(sessionId)) return;
+		inFlight.add(sessionId);
+		lastChecked.set(sessionId, current);
+		try {
+			const found = await detect(agent);
+			if (found === null) registry.forget(sessionId);
+			else registry.remember(sessionId, found);
+		} catch {
+			registry.forget(sessionId);
+		} finally {
+			inFlight.delete(sessionId);
+		}
+	};
+	ctx.on("agent/created", async ({ agent }) => {
+		await refresh(agent);
+	});
+}
+// src/index.ts
+/** Plugin id: package name, bundle row id, browser module id. */
+const name = "dsh-worktree-switch";
+/**
+* Services this plugin cannot work without.
+*
+* `worktrees` is provided by the row this bundle's patch inserts next to its
+* own, so Cordis holds this plugin until that row has mounted.
+*/
+const inject = [
+	"agents",
+	"connection",
+	"subprocess",
+	"worktrees",
+	"workingDirectory"
+];
+/** 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.")
+});
+/**
+* Mount the host half.
+* @param ctx - Host context.
+* @param config - validated row config.
+*/
+function apply(ctx, config) {
+	const scopes = new SessionScopeRegistry();
+	const toggle = createWorktreeToggle(ctx, {
+		defaultEnabled: config.defaultEnabled,
+		onScope: (sessionId, scope) => {
+			if (scope === null) scopes.forget(sessionId);
+			else scopes.remember(sessionId, scope);
+		}
+	});
+	installWorktreeScope(ctx, {
+		registry: scopes,
+		detect: (agent, signal) => detectSessionScope(ctx, agent, signal)
+	});
+	if (config.guardSourceCheckout) installSourceCheckoutGuard(ctx, scopes);
+	registerWorktreeRoutes(ctx, toggle);
+}
+export { Config, apply, inject, name };
+
+//# sourceMappingURL=index.js.map