dsh-worktree-switch 0.2.1 → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 deepseek-plugins contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,20 +2,33 @@
 
 在新会话屏幕的输入框工具行里放一个 **Worktree 开关**。默认打开（按项目记忆）：
 打开时立刻在 `<项目根>/.dsh/worktrees/<名字>` 建一份仓库副本，并把这条会话的工作
-目录切进去；关掉时什么都不做，会话就在原目录里跑。副本不会自动消失、也不会自动合并，
-用户可以在 **Worktrees 面板**里把它丢弃，或者自己把分支合回源仓库。
+目录切进去；在发出第一条消息之前再关掉，会话会被切回项目目录，开关自己刚建的干净
+副本也一并删掉——关掉就是撤销这次隔离。副本不会自动消失、也不会自动合并，用户可以
+在 **Worktrees 面板**里把它丢弃，或者自己把分支合回源仓库。会话在副本里时，宿主半还会
+给模型一条工作区说明，并拒绝把 git 指向主检出的 shell 调用（可关）。
 
 ## 它做什么
 
 - **开关**（`conversation.input.left` 槽，只在空白新会话的 hero 上出现）：显示本会话
-  当前的副本状态——检查中 / 关闭 / 创建中 / 就绪（显示名字）/ 失败（显示原因 + 重试）
-  / 不可用（项目不是 Git 仓库）。开关位置本身记的是"这个项目的新会话要不要隔离"。
-- **创建**发生在开关打开的那一刻，早于第一条消息。副本名 = 分支名 = 池内目录名，形如
+  当前的副本状态——检查中 / 关闭 / 创建中 / 离开中 / 就绪（显示名字）/ 失败（显示原因 +
+  重试）/ 不可用（项目不是 Git 仓库）。开关位置本身记的是"这个项目的新会话要不要隔离"。
+- **创建**发生在开关打开的那一刻，早于第一条消息；**关闭**发生在第一条消息之前时，
+  会话被切回项目目录，开关在这次打开中建的那份干净副本被删除（脏副本或开关之前就存在
+  的副本留在池里，交给面板处理）。副本名 = 分支名 = 池内目录名，形如
   `quiet-harbor-3fa9`，由插件生成，短且唯一。
-- **创建失败不回落**：提示词不发送，错误就地显示。从检查开始、到副本就绪之前（或失败
-  之后），开关通过 `ctx.conversation.blocks` 把该会话的输入框置为"暂停发送"；重试成功、
-  关掉开关（确认不要隔离）或副本就绪时才解除。关掉开关是明确的退出方式——它表示"这条
-  会话就在原目录里跑"，而不是假装隔离成功。
+- **创建失败不回落**：提示词不发送，错误就地显示。从检查开始、到副本就绪之前、离开副本
+  的过程中（或失败之后），开关通过 `ctx.conversation.blocks` 把该会话的输入框置为"暂停
+  发送"；重试成功、关掉开关（确认不要隔离）或副本就绪时才解除。关掉开关是明确的退出
+  方式——它表示"这条会话就在原目录里跑"，而不是假装隔离成功。
+- **会话范围说明**：会话在副本里时，宿主半跟着每轮请求给模型补一条上下文（紧跟工作目录那
+  行）：当前目录是 `<项目>` 的 linked worktree 副本，git 与文件操作在副本里做，主检出是源。
+  它会随恢复会话、每次进/出副本重新推导，回到项目目录后自动消失。这是**提示**，不是权限
+  边界——真正的写隔离仍取决于沙箱根（见「已知边界」）。
+- **主检出守卫**：会话在副本里时，`tools/pre-execute` 会拦下“把 git 指向主检出”的 bash
+  调用（命令里出现主检出的绝对路径，或 `workdir` 落在主检出里），拒绝原因直接告诉模型
+  在副本里该怎么做（`git fetch origin main` + `merge`/`rebase`）。这是启发式拦截，不是
+  沙箱边界：`cd ..` 之类的相对逃逸、shell 变量展开不在它的覆盖范围内；配置
+  `guardSourceCheckout: false` 可关掉。拦下的是 git，主检出里的普通写入仍然由沙箱放行。
 - **面板**（侧边栏条目 + 自己的页面）：按项目列出该仓库的所有 linked worktree（包括
   手工 `git worktree add` 出来的），含名字、分支、路径、创建时间和未提交改动数；丢弃
   需要第二次确认，且**有未提交改动时拒绝丢弃**并说明原因。丢弃会删掉检出目录和分支。
@@ -47,8 +60,9 @@ dsh --profile web --dump-config    # 应能看到 "# == dsh-worktree-switch" 和
    未提交内容留在原地。
 4. 侧边栏出现 **Worktree** 入口：打开后按项目列出磁盘上的副本，含创建时间与未提交改动。
 5. 想丢弃一份副本：点两次 Discard（第二次是确认）；有未提交改动时按钮禁用并说明原因。
-6. 想换个项目默认：在新会话的开关上拨一下。关掉只影响**下一个**会话，当前会话如果已经
-   建好副本，仍继续在副本里跑（提示里会写明这一点）。
+6. 开关只在空白会话上出现：发第一条消息之前关掉，会把会话切回项目目录并删掉刚建的空
+   副本；发过消息之后开关消失，副本留在池里，由面板丢弃。拨开关同时记住这个项目下次
+   的默认位置。
 
 ## 配置
 
@@ -77,6 +91,14 @@ worktree 服务自己的 `directory` 选项——本插件不另存一份设置
 - 目录对每个项目都生效（是相对路径，不是在某个绝对位置开池）。若想按项目不同，只能
   在项目里放不同的 profile——目前没做这种粒度。
 
+**行 id 撞车**：dsh 0.2.2 的 Forge bundle（`@deepseek-ai/dsh-experimental-forge-bundle`）
+也插入一行 `id: worktree`。Loader 按行 id 只留一条、后层覆盖，所以本包的
+`directory: '.dsh/worktrees'` 只在**本包的层排在那份 bundle 之后**时才生效——默认情况正是
+如此（profile 先列宿主 bundle，再列装进来的插件）。如果你手动调整了 bundle 顺序，请在
+profile 的 patch 层里按上面的写法重新声明 `directory`，否则池会静默退回 harness 的默认
+目录（`.agents/worktrees`）。这条只影响目录位置，开关、面板与丢弃逻辑都按服务实际用的
+池子工作。
+
 改完重启 profile 生效。已经在旧目录里的副本不会消失：面板列的是仓库的所有 linked
 worktree，所以新旧目录的副本都会出现，可以照常丢弃。
 
@@ -85,6 +107,7 @@ worktree，所以新旧目录的副本都会出现，可以照常丢弃。
 | 字段 | 默认 | 含义 |
 |---|---|---|
 | `defaultEnabled` | `true` | 用户从未在这个项目上拨过开关时，新会话是否默认隔离。用户拨过一次后，按项目记在浏览器 localStorage 里，优于此项。 |
+| `guardSourceCheckout` | `true` | 会话在副本里时，用 `tools/pre-execute` 拒绝把 git 指向主检出的 bash 调用。关掉就只剩提示。 |
 
 ## 目录与命名
 
@@ -105,18 +128,22 @@ worktree，所以新旧目录的副本都会出现，可以照常丢弃。
   定位文件）显示的是源项目根，而不是副本。这是刻意的：沙箱边界与侧边栏归属都依赖它。
 - 沙箱边界仍是源项目根，因此副本不是"写隔离"，它隔离的是**提交与未提交改动**：
   助手在副本里改的文件不会落到源检出的工作树里，但同一会话仍可写源项目根下的文件。
+  主检出守卫只覆盖 bash 里明显指向主检出的 git 调用，是提示之外的兜底，不是权限。
 - 不自动合并、不自动回收、不支持多仓库、不识别旧插件的 `.worktree-space/` 目录。
 
 ## 实现
 
-宿主半（`src/index.ts`）只做两件事：拿 `cordis.patch.yml` 挂上的 `ctx.worktrees` 和
-`ctx.sessionController`，把四个动词注册成 `/api/dsh-worktree-switch/<verb>` 上的精确
-Fetch 路由（`src/host/routes.ts`），说 `client-request` / `server-response` 信封：
+宿主半（`src/index.ts`）做三件事：拿 `cordis.patch.yml` 挂上的 `ctx.worktrees` 和
+`ctx.sessionController`，把五个动词注册成 `/api/dsh-worktree-switch/<verb>` 上的精确
+Fetch 路由（`src/host/routes.ts`），说 `client-request` / `server-response` 信封；另注册一条
+`systemPrompt.context`（`worktree-switch:scope`），内容来自 `SessionScopeRegistry`，由五个
+动词、`agent/created` 和每次组装时的目录校验共同维护。
 
 | 动词 | 入参 | 行为 |
 |---|---|---|
 | `status` | `{ sessionId }` | 解析仓库根、本会话是否已在某个 linked worktree 里、源仓库未提交改动数 |
 | `prepare` | `{ sessionId }` | 幂等；必要时经 `ctx.worktrees.create` 建副本并切目录，同名冲突自动换名重试 |
+| `release` | `{ sessionId }` | 把会话切回项目目录；删掉开关自己建的那份干净副本，脏副本与非开关建的副本留在池里 |
 | `list` | `{ path }` | 列出该仓库除主检出外的所有 linked worktree，返回名字/分支/路径/创建时间/改动数 |
 | `discard` | `{ path, name }` | 干净才删：`git worktree remove` + `git branch -D`；改动非空则拒绝 |
 
@@ -133,7 +160,7 @@ pnpm --filter dsh-worktree-switch test
 pnpm build          # 构建全部包并校验 exports / bundle patch 文件存在
 ```
 
-测试只有两条接缝：宿主半的四个动词（真实临时 Git 仓库 + 真实服务，`tests/host.spec.ts`）
+测试只有两条接缝：宿主半的五个动词（真实临时 Git 仓库 + 真实服务，`tests/host.spec.ts`）
 和浏览器半的槽注册与渲染（真实 `SlotRegistry` + 假 `connection`/`conversation`，
 `tests/*.client.spec.tsx`）。不断言内部 Git 调用次数，也不测上游 worktree 服务自己的
 Git 细节。

package/cordis.patch.yml

@@ -5,6 +5,14 @@
 # bundle uses: a profile that already mounts the model-facing worktree tool
 # overrides this row instead of registering the `worktrees` service twice
 # (Cordis throws on a duplicate service name).
+#
+# dsh 0.2.2's @deepseek-ai/dsh-experimental-forge-bundle inserts that same
+# `worktree` id too. Loader keeps one row per id and the last layer wins, so
+# this row's `config` (including `directory`) survives only while this bundle's
+# layer is applied after the bundle that owns the other `worktree` row — which
+# is the normal case, because a profile lists host bundles before installed
+# plugins. If you reorder bundles, restate `directory` in the profile's own
+# patch layer, or the pool silently falls back to the service default.
 - insert:
     - id: worktree
       name: '@deepseek-ai/dsh-experimental-worktree'

package/lib/client.js

@@ -30,6 +30,7 @@ function chipLabel(state, t) {
 		case "checking": return t("chip.checking");
 		case "off": return t("chip.off");
 		case "creating": return t("chip.creating");
+		case "reverting": return t("chip.reverting");
 		case "ready": return t("chip.ready", { name: state.worktree?.name ?? "" });
 		case "failed": return t("chip.failed");
 		case "disabled": return t("chip.disabled");
@@ -46,6 +47,7 @@ function chipHint(state, t) {
 		case "checking": return t("chip.hint.checking");
 		case "off": return t("chip.hint.off");
 		case "creating": return t("chip.hint.creating");
+		case "reverting": return t("chip.hint.reverting");
 		case "ready": {
 			const parts = [t("chip.hint.ready", {
 				branch: state.worktree?.branch ?? "",
@@ -53,6 +55,7 @@ function chipHint(state, t) {
 			})];
 			if (!state.intent) parts.push(t("chip.hint.intentOff", { name: state.worktree?.name ?? "" }));
 			if (state.sourceDirty > 0) parts.push(t("chip.hint.dirty", { count: state.sourceDirty }));
+			if (state.error !== null) parts.push(state.error);
 			return parts.join(" ");
 		}
 		case "failed": {
@@ -79,7 +82,7 @@ function WorktreeChip(props) {
 			block(null);
 			return;
 		}
-		const reason = state.phase === "checking" ? t("chip.blocked.checking") : !state.intent ? null : state.phase === "creating" ? t("chip.blocked.creating") : state.phase === "failed" ? t("chip.blocked.failed") : null;
+		const reason = state.phase === "checking" ? t("chip.blocked.checking") : state.phase === "creating" ? t("chip.blocked.creating") : state.phase === "reverting" ? t("chip.blocked.reverting") : state.phase === "failed" && state.intent ? t("chip.blocked.failed") : null;
 		block(reason);
 	}, [
 		block,
@@ -93,7 +96,7 @@ function WorktreeChip(props) {
 	}, [block]);
 	if (!hero) return null;
 	const hint = chipHint(state, t);
-	const locked = state.phase === "checking" || state.phase === "disabled";
+	const locked = state.phase === "checking" || state.phase === "disabled" || state.phase === "reverting";
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 		className: "dsh-wt-chip",
 		"data-phase": state.phase,
@@ -411,6 +414,7 @@ const en = {
 	"chip.checking": "Worktree…",
 	"chip.off": "Worktree off",
 	"chip.creating": "Creating worktree…",
+	"chip.reverting": "Leaving worktree…",
 	"chip.ready": "Worktree: {name}",
 	"chip.failed": "Worktree failed",
 	"chip.retry": "Retry",
@@ -419,13 +423,15 @@ const en = {
 	"chip.hint.off": "New sessions in this project start in the project directory.",
 	"chip.hint.on": "This session runs in a copy of the project; the source checkout is untouched.",
 	"chip.hint.creating": "Creating a checkout inside the project…",
+	"chip.hint.reverting": "Moving this session back to the project directory…",
 	"chip.hint.ready": "Branch {branch} at {path}",
 	"chip.hint.failed": "The copy was not created, so this session is still in the project directory.",
 	"chip.hint.disabled": "This project is not a Git repository, so there is nothing to copy.",
 	"chip.hint.dirty": "The source checkout has {count} uncommitted change(s); the copy starts from the last commit.",
-	"chip.hint.intentOff": "Applies to the next session; this one keeps {name}.",
+	"chip.hint.intentOff": "Turning off could not leave {name}; this session still runs in it.",
 	"chip.blocked.checking": "Checking whether this session gets a worktree…",
 	"chip.blocked.creating": "Creating the worktree before the first prompt…",
+	"chip.blocked.reverting": "Leaving the worktree before the first prompt…",
 	"chip.blocked.failed": "The worktree could not be created. Retry, turn the switch off, or discard the failed copy first.",
 	"panel.title": "Worktrees",
 	"panel.subtitle": "Copies created by the Worktree switch: one checkout and one branch each. Discard removes both.",
@@ -455,6 +461,7 @@ const zh = {
 	"chip.checking": "Worktree…",
 	"chip.off": "Worktree 已关",
 	"chip.creating": "正在创建 Worktree…",
+	"chip.reverting": "正在离开 Worktree…",
 	"chip.ready": "Worktree：{name}",
 	"chip.failed": "Worktree 创建失败",
 	"chip.retry": "重试",
@@ -463,13 +470,15 @@ const zh = {
 	"chip.hint.off": "这个项目的新会话直接在项目目录里开始。",
 	"chip.hint.on": "本会话在项目的一份副本里运行，源仓库不受影响。",
 	"chip.hint.creating": "正在项目里创建检出…",
+	"chip.hint.reverting": "正在把本会话切回项目目录…",
 	"chip.hint.ready": "分支 {branch}，位于 {path}",
 	"chip.hint.failed": "副本没有创建成功，本会话仍然在项目目录里。",
 	"chip.hint.disabled": "这个项目不是 Git 仓库，没有可复制的内容。",
 	"chip.hint.dirty": "源仓库有 {count} 处未提交改动；副本会从最后一次提交开始。",
-	"chip.hint.intentOff": "仅对下一个会话生效；本会话仍然使用 {name}。",
+	"chip.hint.intentOff": "关闭时没能离开 {name}，本会话仍在副本里运行。",
 	"chip.blocked.checking": "正在检查本会话是否需要 Worktree…",
 	"chip.blocked.creating": "正在创建 Worktree，副本就绪前暂停发送…",
+	"chip.blocked.reverting": "正在离开 Worktree，切回项目目录前暂停发送…",
 	"chip.blocked.failed": "Worktree 创建失败。请重试、关闭开关，或先丢弃失败的副本。",
 	"panel.title": "Worktree",
 	"panel.subtitle": "Worktree 开关创建的副本：每份副本是一个检出加一个分支，丢弃会同时删掉两者。",
@@ -623,6 +632,10 @@ var InternalBinding = class {
 	started = false;
 	/** The project whose remembered choice is in play; null until status answers. */
 	project = null;
+	/** A create is in flight; a second one would race the same copy. */
+	creating = false;
+	/** The release in flight, shared by callers that ask to leave at once. */
+	releasing = null;
 	face;
 	/**
 	* @param ctx - browser Cordis context.
@@ -683,6 +696,7 @@ var InternalBinding = class {
 					...base,
 					phase: "ready"
 				});
+				if (!intent) this.release();
 				return;
 			}
 			if (!intent) {
@@ -702,8 +716,10 @@ var InternalBinding = class {
 	}
 	/** Create the copy for a session the switch says should have one. */
 	async create() {
+		if (this.creating) return;
 		const before = this.store.getSnapshot();
-		if (before.repositoryRoot === null) return;
+		if (before.repositoryRoot === null || !before.intent) return;
+		this.creating = true;
 		this.store.set({
 			...before,
 			phase: "creating",
@@ -712,6 +728,10 @@ var InternalBinding = class {
 		try {
 			const prepared = await callHost(this.ctx, "prepare", { sessionId: this.sessionId }, this.signal);
 			const now = this.store.getSnapshot();
+			if (!now.intent) {
+				if (now.phase === "reverting") this.release();
+				return;
+			}
 			this.store.set({
 				...now,
 				phase: "ready",
@@ -724,12 +744,7 @@ var InternalBinding = class {
 			if (this.signal.aborted) return;
 			const now = this.store.getSnapshot();
 			if (!now.intent) {
-				this.store.set({
-					...now,
-					phase: "off",
-					worktree: null,
-					error: null
-				});
+				if (now.phase === "reverting") this.release();
 				return;
 			}
 			this.store.set({
@@ -737,22 +752,76 @@ var InternalBinding = class {
 				phase: "failed",
 				error: messageOf(error)
 			});
+		} finally {
+			this.creating = false;
+		}
+	}
+	/**
+	* Leave the copy this session runs in, so "off" means the project directory.
+	* Concurrent callers share one round trip.
+	* @returns completion of the leave.
+	*/
+	release() {
+		const running = this.releasing;
+		if (running !== null) return running;
+		const operation = this.leave().finally(() => {
+			if (this.releasing === operation) this.releasing = null;
+		});
+		this.releasing = operation;
+		return operation;
+	}
+	/** Ask the host to undo the copy and settle the switch on what it reported. */
+	async leave() {
+		const before = this.store.getSnapshot();
+		this.store.set({
+			...before,
+			phase: "reverting",
+			error: null
+		});
+		try {
+			await callHost(this.ctx, "release", { sessionId: this.sessionId }, this.signal);
+			if (this.signal.aborted) return;
+			const now = this.store.getSnapshot();
+			this.store.set({
+				...now,
+				phase: "off",
+				intent: false,
+				worktree: null,
+				error: null
+			});
+		} catch (error) {
+			if (this.signal.aborted) return;
+			const now = this.store.getSnapshot();
+			this.store.set({
+				...now,
+				phase: now.worktree === null ? "off" : "ready",
+				intent: false,
+				error: messageOf(error)
+			});
 		}
 	}
 	/** Persist and apply one switch move. */
 	setIntent(next) {
 		const state = this.store.getSnapshot();
-		if (state.phase === "checking" || state.phase === "disabled") return;
+		if (state.phase === "checking" || state.phase === "disabled" || state.phase === "reverting") return;
 		if (this.project !== null) writeIntent(this.project, next);
-		const phase = !next && state.phase === "failed" ? "off" : state.phase;
+		if (!next) {
+			if (state.intent === next) return;
+			this.store.set({
+				...state,
+				intent: false,
+				error: null
+			});
+			this.release();
+			return;
+		}
+		if (state.intent === next) return;
 		this.store.set({
 			...state,
-			phase,
-			intent: next,
-			error: next ? state.error : null
+			intent: true,
+			error: null
 		});
-		if (!next || state.intent === next) return;
-		if (phase === "off") this.create();
+		if (state.phase === "off" || state.phase === "failed") this.create();
 	}
 	/** Re-run the host round trip with the switch on. */
 	retry() {

package/lib/index.d.ts

@@ -13,6 +13,8 @@ export declare const inject: string[];
 export interface Config {
   /** Default for a project the user has never switched either way. */
   defaultEnabled: boolean;
+  /** Refuse shell commands that run Git against the project checkout while the session is in a copy. */
+  guardSourceCheckout: boolean;
 }
 /** Schemastery schema for {@link Config}. */
 export declare const Config: Schema<Config>;