@deepseek-ai/dsh-experimental-worktree 0.0.0-stage → 0.2.1-alpha.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+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.i18n.yaml

@@ -0,0 +1,37 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/experimental/worktree/README.md
+/:
+  en: abb4e123de7c0434
+  zh: 40f28bb7301d3d0a
+/deepseek-ai-dsh-experimental-worktree:
+  en: 0fbe7569a8801a86
+  zh: 794c1773e8825da5
+/deepseek-ai-dsh-experimental-worktree/summary:
+  en: 954278bb62827f55
+  zh: cb96870bfb05ec23
+/deepseek-ai-dsh-experimental-worktree/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 2f8a621b991260a1
+/deepseek-ai-dsh-experimental-worktree/use-this-package:
+  en: 68aef00468f63589
+  zh: a3cdb93c91ff1b9e
+/deepseek-ai-dsh-experimental-worktree/understand-the-implementation:
+  en: 6971a7ca9073bef1
+  zh: b977c28a75c7f963
+/deepseek-ai-dsh-experimental-worktree/further-exploration:
+  en: 5bcd45f0bba56207
+  zh: fd6342fd6bac5179
+/deepseek-ai-dsh-experimental-worktree/model-experience:
+  en: 4a3506885138c925
+  zh: 7ac65dc18dc5c292
+/deepseek-ai-dsh-experimental-worktree/model-experience/kv-cache-effect:
+  en: 6826dfaadb24f3da
+  zh: 2e2ee715247fc015
+/deepseek-ai-dsh-experimental-worktree/known-limitations-and-deferred-work:
+  en: 0adcf97622e86f3b
+  zh: 8bcdc336011cd7e1
+/deepseek-ai-dsh-experimental-worktree/known-limitations-and-deferred-work/dev-note:
+  en: ad12746a6cc96d8a
+  zh: 66275f30a35c88e4

package/README.md

@@ -1,3 +1,98 @@
-# Temporary Holding Version
+---
+description: "Create and enter a retained Git worktree under the calling Session file policy."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @deepseek-ai/dsh-experimental-worktree
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Create an isolated checkout from a local commit and continue the same Session in it. Each operation creates a new named branch and leaves the source checkout intact. The existing sandbox governs all writes. Leaving the checkout retains its files and branch.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Mount the service alongside `workingDirectory`, `fs`, `subprocess`, `sandbox`, and `sandboxPolicy` providers. Add the tool package when models need the operation.
+
+```yaml
+- name: '@deepseek-ai/dsh-experimental-worktree'
+- name: '@deepseek-ai/dsh-experimental-tool-worktree'
+```
+
+`ctx.worktrees.create(agent, { name?, from? }, signal?)` creates a new branch and checkout, then enters the canonical checkout directory through `ctx.workingDirectory.set`. `from` resolves to a local commit before creation and defaults to `HEAD`; staged, unstaged, untracked, and ignored source files are not copied. `baseCommit` reports the resolved commit object name; repository-local replacement refs still apply to the checked-out content. Checkout disables configured Git clean, smudge, and process filters without changing repository configuration. An existing branch or checkout path is an error. The returned record contains `path`, `branch`, `baseCommit`, and `repositoryRoot`.
+
+The default checkout directory is `<current checkout root>/.agents/worktrees/<name>`. The returned `repositoryRoot` is the top-level directory of the caller’s current checkout; when it is a linked checkout, the pool is nested inside it. Omitted names use `worktree-` plus a UUID. The service writes a `.gitignore` containing `*` and a trailing newline only when its allocation creates the pool; existing files and ignore rules are preserved. Relative `directory`, generated `namePrefix`, executable choices, and process limits are configurable in the [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-experimental-worktree).
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+Git and directory allocation run through the mounted subprocess and sandbox providers with the calling Session's existing file policy. Creation does not widen write access to the destination or shared Git administration directory. Directory creation claims the destination exclusively; cancellation and failed setup can leave retained artifacts, whose path appears in the error. Service disposal aborts pending operations and waits for their settlement.
+
+| Source | Responsibility |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Resolve the source revision, create the checkout, and publish the new working directory |
+| [`src/process.ts`](src/process.ts) | Confine literal argv, cap output, and await process termination |
+| [`src/directory.ts`](src/directory.ts) | Claim the destination and initialize a newly created pool's ignore file |
+
+No runtime invariant companion is published: Git owns checkout registration and the working-directory service owns the Session directory; this package retains no independent projection of either.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Worktree subsystem](../../../docs/subsystems/worktrees.md) — request, result, and service reference.
+- [Working directory](../../session/working-directory/README.md) — recorded Session directory and directory changes.
+- [Worktree tool](../tool-worktree/README.md) — model-facing creation.
+- [Subprocess](../../subprocess/subprocess/README.md) — process ownership and execution worlds.
+- [Creation decision](../../../.agents/notes/implemented/feature/2026-09-13-explicit-worktree-creation.md) — retained checkouts and existing write grants.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+Indirectly, through the worktree tool's creation result and the working-directory service's recorded Session context.
+
+#### KV Cache effect
+
+This package contributes no prompt text. Its consumers own the appended tool result and recorded directory context.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **Retained artifacts** — leaving a worktree keeps its branch and files. Setup failures can also retain partial artifacts; removal, pruning, and branch deletion belong to the user or another consumer.
+- **Local revisions only** — creation does not fetch commits or missing partial-clone objects, initialize submodules, install dependencies, or copy uncommitted files. On Git that meets the execution requirements, missing local objects cause creation to fail.
+- **Filtered representations** — checkout skips configured filters to avoid executing repository-configured programs or triggering implicit downloads. Git LFS pointers and encrypted blobs stay in their stored representation; hydration or decryption is a separate user-controlled operation.
+- **Execution requirements** — the subprocess provider must offer Git and Node in the same execution world as the filesystem provider. Git must honor `GIT_NO_LAZY_FETCH`, which Git 2.45 and the 2.39.4, 2.40.2, 2.41.1, 2.42.2, 2.43.4, and 2.44.1 maintenance releases do; older releases ignore it and proceed instead of failing, so creation can fetch missing partial-clone objects from a promisor remote. The `git --no-lazy-fetch` option would reject these releases, but it exists only in Git 2.45 and later and also rejects the patched maintenance releases. The existing sandbox must permit all checkout and shared Git metadata writes.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+The sandboxed Node child supplies exclusive directory creation, which the [filesystem service](../../fs/fs/src/index.ts) does not expose, and identifies whether this service created the pool. The filesystem contract permits bare providers such as [fs-local](../../fs/fs-local/src/index.ts) to ignore `sandboxPolicy` on writes; `createIfAbsent` protects a file but neither enforces permissions nor identifies who created its directory. Keeping directory allocation and ignore-file creation under the same process sandbox as Git preserves refusal of existing checkout paths and the condition for creating `.gitignore`.
+
+</details>

package/README.zh.md

@@ -0,0 +1,98 @@
+---
+description: "按照调用 Session 的文件策略创建并进入保留的 Git 工作树。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-experimental-worktree
+
+[English](README.md) | 中文
+
+## 概述
+
+从本地提交创建隔离的检出目录，并在其中继续同一个 Session。每次操作创建新的具名分支，源检出目录保持不变。所有写入均受现有沙箱约束。离开检出目录会保留文件与分支。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [了解实现](#understand-the-implementation)
+- [深入探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与待办工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+将服务与 `workingDirectory`、`fs`、`subprocess`、`sandbox` 和 `sandboxPolicy` 提供方一起挂载。模型需要此操作时，再添加工具包。
+
+```yaml
+- name: '@deepseek-ai/dsh-experimental-worktree'
+- name: '@deepseek-ai/dsh-experimental-tool-worktree'
+```
+
+`ctx.worktrees.create(agent, { name?, from? }, signal?)` 创建新分支与检出目录，再通过 `ctx.workingDirectory.set` 进入规范化的检出目录。`from` 在创建前解析为本地提交，默认是 `HEAD`；暂存、未暂存、未跟踪以及被忽略的源文件均不复制。`baseCommit` 报告解析出的提交对象名称；仓库本地的替换引用仍作用于检出的内容。检出操作禁用已配置的 Git clean、smudge 和 process 过滤器，不修改仓库配置。分支或检出路径已存在时会报错。返回记录包含 `path`、`branch`、`baseCommit` 和 `repositoryRoot`。
+
+默认检出目录是 `<current checkout root>/.agents/worktrees/<name>`。返回的 `repositoryRoot` 是调用方当前检出目录的顶层目录；如果它是链接检出目录，工作树父目录就嵌套在其中。省略名称时，使用 `worktree-` 加 UUID。仅当服务的分配操作创建了父目录时，服务才会写入内容为 `*` 加换行符的 `.gitignore`；已有文件与忽略规则保持不变。相对路径 `directory`、生成名称使用的 `namePrefix`、可执行程序与进程限制可在[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-experimental-worktree)中查阅。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 了解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+Git 与目录分配通过挂载的子进程及沙箱提供方执行，沿用调用 Session 的文件策略。创建操作不会扩大目标目录或共享 Git 管理目录的写权限。目录创建独占申请目标路径；取消或初始化失败可能留下已有产物，错误会包含其路径。服务销毁会中止待完成操作，并等待它们结束。
+
+| 源码 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 解析源提交、创建检出目录并发布新的工作目录 |
+| [`src/process.ts`](src/process.ts) | 约束字面参数、限制输出并等待进程终止 |
+| [`src/directory.ts`](src/directory.ts) | 申请目标目录并初始化新建工作树父目录的忽略文件 |
+
+本包不发布运行时不变量伴随入口：Git 拥有工作树注册信息，工作目录服务拥有 Session 目录；本包不保留二者的独立投影。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 深入探索
+
+- [工作树子系统](../../../docs/subsystems/worktrees.zh.md)——请求、结果与服务参考。
+- [工作目录](../../session/working-directory/README.zh.md) — 记录的 Session 目录与目录切换。
+- [工作树工具](../tool-worktree/README.zh.md) — 面向模型的创建操作。
+- [子进程](../../subprocess/subprocess/README.zh.md) — 进程所有权与执行环境。
+- [创建决策](../../../.agents/notes/implemented/feature/2026-09-13-explicit-worktree-creation.zh.md) — 保留检出目录与既有写权限。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+通过工作树工具的创建结果与工作目录服务记录的 Session 上下文间接影响模型。
+
+#### KV Cache 影响
+
+本包不贡献提示文本。其消费方负责追加工具结果与记录的目录上下文。
+
+## 已知限制与待办工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **保留产物**——离开工作树会保留其分支和文件。初始化失败也可能留下部分产物；移除、清理注册信息与删除分支由用户或其他消费方负责。
+- **仅限本地提交**——创建操作不会获取远端提交或部分克隆中缺失的对象、初始化子模块、安装依赖或复制未提交文件。Git 满足执行要求时，本地对象缺失会导致创建失败。
+- **过滤器处理前的内容**——检出时跳过已配置的过滤器，以避免执行仓库配置的程序或隐式下载。Git LFS 指针与加密 blob 保持存储时的形式；拉取实体内容或解密由用户另行执行。
+- **执行要求**——子进程提供方必须在与文件系统提供方相同的执行环境中提供 Git 与 Node。Git 必须识别 `GIT_NO_LAZY_FETCH`：Git 2.45 及 2.39.4、2.40.2、2.41.1、2.42.2、2.43.4、2.44.1 维护版本均支持；更早的版本会忽略该变量并继续执行而不报错，因此创建操作可能从 promisor 远程获取缺失的部分克隆对象。`git --no-lazy-fetch` 选项会拒绝这些版本，但它仅在 Git 2.45 及以后存在，也会拒绝上述已修补的维护版本。现有沙箱必须允许写入检出目录与共享 Git 元数据。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+沙箱内的 Node 子进程提供[文件系统服务](../../fs/fs/src/index.ts)未公开的独占目录创建能力，并确定父目录是否由本服务创建。文件系统契约允许 [fs-local](../../fs/fs-local/src/index.ts) 等普通提供方在写入时忽略 `sandboxPolicy`；`createIfAbsent` 保护文件，但既不执行权限约束，也不确定目录由谁创建。将目录分配和忽略文件创建放在与 Git 相同的进程沙箱内，可保留对已有检出路径的拒绝行为，并落实创建 `.gitignore` 的条件。
+
+</details>

package/lib/index.js

@@ -0,0 +1,368 @@
+import { randomUUID } from "node:crypto";
+import { Service } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
+import { MAX_TIMER_DELAY_MS, deadline } from "@deepseek-ai/dsh-timeout";
+//#region lib/types/directory.js
+/** Static child program for exclusive checkout-directory allocation inside the process sandbox. */
+/**
+* The child receives the configured root and destination as literal argv. Existing roots retain
+* their files; only the process that creates a root writes its self-ignoring .gitignore.
+*/
+const PREPARE_DIRECTORY = `
+import fs from 'node:fs/promises';
+import path from 'node:path';
+async function main() {
+  const [root, destination] = process.argv.slice(1);
+  await fs.mkdir(path.dirname(root), { recursive: true });
+  let created = false;
+  try {
+    await fs.mkdir(root);
+    created = true;
+  } catch (error) {
+    if (error.code !== 'EEXIST' || !(await fs.stat(root)).isDirectory()) throw error;
+  }
+  if (created) await fs.writeFile(path.join(root, '.gitignore'), '*\\n', { flag: 'wx' });
+  await fs.mkdir(path.dirname(destination), { recursive: true });
+  await fs.mkdir(destination);
+}
+main().catch(error => { console.error(error.message); process.exitCode = 1; });
+`;
+//#endregion
+//#region lib/types/process.js
+/** Bounded, cancellable commands under the calling Session's existing file policy. */
+var __addDisposableResource = function(env, value, async) {
+	if (value !== null && value !== void 0) {
+		if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+		var dispose, inner;
+		if (async) {
+			if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+			dispose = value[Symbol.asyncDispose];
+		}
+		if (dispose === void 0) {
+			if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+			dispose = value[Symbol.dispose];
+			if (async) inner = dispose;
+		}
+		if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+		if (inner) dispose = function() {
+			try {
+				inner.call(this);
+			} catch (e) {
+				return Promise.reject(e);
+			}
+		};
+		env.stack.push({
+			value,
+			dispose,
+			async
+		});
+	} else if (async) env.stack.push({ async: true });
+	return value;
+};
+var __disposeResources = (function(SuppressedError) {
+	return function(env) {
+		function fail(e) {
+			env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+			env.hasError = true;
+		}
+		var r, s = 0;
+		function next() {
+			while (r = env.stack.pop()) try {
+				if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+				if (r.dispose) {
+					var result = r.dispose.call(r.value);
+					if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) {
+						fail(e);
+						return next();
+					});
+				} else s |= 1;
+			} catch (e) {
+				fail(e);
+			}
+			if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+			if (env.hasError) throw env.error;
+		}
+		return next();
+	};
+})(typeof SuppressedError === "function" ? SuppressedError : function(error, suppressed, message) {
+	var e = new Error(message);
+	return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+/** Clear inherited repository, attribute-tree, command-line configuration, and replacement-ref selectors. */
+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]));
+/**
+* Run an argv without a shell and await termination of its managed process range.
+* @param ctx - subprocess and sandbox providers in the same execution world.
+* @param config - complete process resource limits.
+* @param policy - unchanged calling Session policy.
+* @param cwd - canonical process working directory.
+* @param argv - executable followed by literal arguments.
+* @param signal - operation cancellation.
+* @param allowedExitCodes - command-specific successful statuses.
+* @param env - command-local environment overrides, applied after Git selector removal.
+* @returns complete bounded stdout and the exit code.
+*/
+async function runCommand(ctx, config, policy, cwd, argv, signal, allowedExitCodes = [0], env = {}) {
+	const env_1 = {
+		stack: [],
+		error: void 0,
+		hasError: false
+	};
+	try {
+		const timeout = __addDisposableResource(env_1, deadline(signal, config.timeoutMs, "WORKTREE_TIMEOUT"), false);
+		timeout.signal.throwIfAborted();
+		const command = [await ctx.subprocess.resolveExecutable(argv[0], void 0, timeout.signal), ...argv.slice(1)];
+		const wrapped = policy.mode === "danger-full-access" ? command : (await ctx.sandbox.confine(command, {
+			...policy,
+			mode: policy.mode
+		}, timeout.signal)).argv;
+		timeout.signal.throwIfAborted();
+		const child = ctx.subprocess.spawn({
+			argv: wrapped,
+			cwd,
+			env: {
+				...GIT_ENV,
+				GIT_TERMINAL_PROMPT: "0",
+				GIT_LFS_SKIP_SMUDGE: "1",
+				GIT_NO_LAZY_FETCH: "1",
+				...env
+			},
+			signal: timeout.signal,
+			graceMs: config.graceMs,
+			stdio: {
+				stdin: "ignore",
+				stdout: { maxBytes: config.maxOutputBytes },
+				stderr: { maxBytes: config.maxOutputBytes }
+			}
+		});
+		try {
+			const outcome = await child.done;
+			timeout.signal.throwIfAborted();
+			const captured = child.collected;
+			const stdout = captured.stdout.readFrom(0);
+			const stderr = captured.stderr.readFrom(0);
+			if (outcome.exitCode === null || !allowedExitCodes.includes(outcome.exitCode)) throw new Error(`worktree command failed (${outcome.signal ?? outcome.exitCode}): ${stderr.text.trim()}`);
+			if (stdout.lossy) throw new Error("worktree command output exceeds maxOutputBytes");
+			return {
+				stdout: stdout.text,
+				exitCode: outcome.exitCode
+			};
+		} finally {
+			child.terminate();
+			await child.waitForExit();
+		}
+	} catch (e_1) {
+		env_1.error = e_1;
+		env_1.hasError = true;
+	} finally {
+		__disposeResources(env_1);
+	}
+}
+//#endregion
+//#region lib/types/index.js
+/** Creates a new Git branch and checkout, then changes the calling Session's working directory. */
+/** Reject path traversal independently of Git's branch-name grammar. */
+function relativePath(value) {
+	return value.length > 0 && !value.includes("\\") && !value.includes(":") && value.split("/").every((part) => part.length > 0 && part !== "." && part !== "..");
+}
+/** Creates retained Git worktrees under the mounted filesystem and sandbox providers. */
+var WorktreeService = class extends Service {
+	static inject = [
+		"workingDirectory",
+		"fs",
+		"subprocess",
+		"sandbox",
+		"sandboxPolicy"
+	];
+	static Config = z.object({
+		directory: z.string().default(".agents/worktrees"),
+		namePrefix: z.string().default("worktree-"),
+		gitCommand: z.string().default("git"),
+		nodeCommand: z.string().default("node"),
+		timeoutMs: z.number().default(6e4),
+		graceMs: z.number().default(3e3),
+		maxOutputBytes: z.number().default(65536)
+	});
+	config;
+	lifetime = new AbortController();
+	pending = /* @__PURE__ */ new Set();
+	constructor(ctx, config) {
+		super(ctx, "worktrees");
+		this.config = config;
+		if (!relativePath(this.config.directory)) throw new Error("worktree: directory must be a relative directory without dot segments");
+		if (!relativePath(`${this.config.namePrefix}name`) || this.config.namePrefix.startsWith("-")) throw new Error("worktree: namePrefix must produce a relative branch name");
+		for (const key of ["gitCommand", "nodeCommand"]) if (this.config[key].trim().length === 0) throw new Error(`worktree: ${key} must not be empty`);
+		for (const key of [
+			"timeoutMs",
+			"graceMs",
+			"maxOutputBytes"
+		]) {
+			const value = this.config[key];
+			if (!Number.isSafeInteger(value) || value <= 0 || value > MAX_TIMER_DELAY_MS) throw new Error(`worktree: ${key} must be a positive integer no greater than ${MAX_TIMER_DELAY_MS}`);
+		}
+		ctx.effect(() => async () => {
+			this.lifetime.abort(/* @__PURE__ */ new Error("worktree service disposed"));
+			await Promise.allSettled(this.pending);
+		});
+	}
+	/**
+	* Create a fresh branch and checkout at a pinned local revision, then enter it.
+	* Existing branches or checkout paths fail. Uncommitted files stay in the source checkout.
+	* Checkout disables configured clean, smudge, and process filters without changing Git config.
+	* Repository-local replacement refs still apply; baseCommit reports the resolved object name.
+	* The new checkout becomes current only after Git setup succeeds. Failures may retain newly
+	* allocated Git/filesystem artifacts; no branch or checkout is removed automatically.
+	* @param agent - caller whose current directory selects the source repository and file policy.
+	* @param request - optional new name and local revision; defaults are generated name and HEAD.
+	* @param signal - cancellation of lookup, creation, and working-directory publication.
+	* @returns canonical checkout path, branch name, pinned commit, and source repository root.
+	*/
+	async create(agent, request = {}, signal) {
+		const operationSignal = signal === void 0 ? this.lifetime.signal : AbortSignal.any([this.lifetime.signal, signal]);
+		operationSignal.throwIfAborted();
+		const operation = this.createCheckout(agent, this.resolve(request), operationSignal);
+		this.pending.add(operation);
+		try {
+			return await operation;
+		} finally {
+			this.pending.delete(operation);
+		}
+	}
+	resolve(request) {
+		const branch = request.name ?? `${this.config.namePrefix}${randomUUID()}`;
+		if (!relativePath(branch) || branch.startsWith("-")) throw new Error("worktree name must be a relative Git branch name");
+		const revision = request.from ?? "HEAD";
+		if (revision.length === 0) throw new Error("worktree from must name a local commit, branch, or tag");
+		return {
+			branch,
+			revision
+		};
+	}
+	async createCheckout(agent, { branch, revision }, signal) {
+		const cwd = await this.ctx.workingDirectory.ensure(agent, signal);
+		const policy = this.ctx.sandboxPolicy.resolve({ session: agent.session });
+		const run = (directory, args, allowedExitCodes, env) => runCommand(this.ctx, this.config, policy, directory, [
+			this.config.gitCommand,
+			"-c",
+			"core.hooksPath=/dev/null",
+			"-c",
+			"core.fsmonitor=false",
+			...args
+		], signal, allowedExitCodes, env);
+		await run(cwd, ["check-ref-format", `refs/heads/${branch}`]);
+		const rootOutput = await run(cwd, ["rev-parse", "--show-toplevel"]);
+		const rootTarget = await this.ctx.fs.resolve(rootOutput.stdout.replace(/\r?\n$/, ""), {
+			cwd,
+			signal
+		});
+		const repositoryRoot = this.ctx.fs.processPath(rootTarget);
+		const baseCommit = (await run(repositoryRoot, [
+			"rev-parse",
+			"--verify",
+			"--end-of-options",
+			`${revision}^{commit}`
+		])).stdout.trim();
+		if ((await run(repositoryRoot, [
+			"show-ref",
+			"--verify",
+			"--quiet",
+			`refs/heads/${branch}`
+		], [0, 1])).exitCode === 0) throw new Error(`worktree branch already exists: ${branch}`);
+		const pool = await this.ctx.fs.resolve(this.config.directory, {
+			cwd: repositoryRoot,
+			signal
+		});
+		const poolPath = this.ctx.fs.processPath(pool);
+		const destination = await this.ctx.fs.resolve(branch, {
+			cwd: poolPath,
+			signal
+		});
+		const path = this.ctx.fs.processPath(destination);
+		if (await this.ctx.fs.lstat(path, void 0, signal) !== void 0) throw new Error(`worktree path already exists: ${path}`);
+		try {
+			await runCommand(this.ctx, this.config, policy, repositoryRoot, [
+				this.config.nodeCommand,
+				"--input-type=module",
+				"-e",
+				PREPARE_DIRECTORY,
+				poolPath,
+				path
+			], signal);
+			await run(repositoryRoot, [
+				"--work-tree",
+				repositoryRoot,
+				"worktree",
+				"add",
+				"--no-checkout",
+				"-b",
+				branch,
+				"--",
+				path,
+				baseCommit
+			]);
+			const configured = await run(path, [
+				"config",
+				"--null",
+				"--name-only",
+				"--get-regexp",
+				"^filter\\."
+			], [0, 1]);
+			const drivers = /* @__PURE__ */ new Set();
+			for (const key of configured.stdout.split("\0")) {
+				const separator = key.lastIndexOf(".");
+				if (separator > 7 && [
+					"clean",
+					"smudge",
+					"process",
+					"required"
+				].includes(key.slice(separator + 1))) drivers.add(key.slice(7, separator));
+			}
+			const overrides = { GIT_CONFIG_COUNT: String(drivers.size * 4) };
+			let index = 0;
+			for (const driver of drivers) for (const attribute of [
+				"clean",
+				"smudge",
+				"process",
+				"required"
+			]) {
+				overrides[`GIT_CONFIG_KEY_${index}`] = `filter.${driver}.${attribute}`;
+				overrides[`GIT_CONFIG_VALUE_${index}`] = attribute === "required" ? "false" : "";
+				index++;
+			}
+			await run(path, [
+				"--work-tree",
+				path,
+				"reset",
+				"--hard",
+				"--no-recurse-submodules",
+				baseCommit
+			], void 0, overrides);
+			return {
+				path: await this.ctx.workingDirectory.set(agent, path, signal),
+				branch,
+				baseCommit,
+				repositoryRoot
+			};
+		} catch (error) {
+			throw new Error(`Could not finish worktree ${branch} at ${path}. Any created checkout and branch are retained. ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+		}
+	}
+};
+//#endregion
+export { WorktreeService, WorktreeService as default };

package/lib/types/directory.d.ts

@@ -0,0 +1,7 @@
+/** Static child program for exclusive checkout-directory allocation inside the process sandbox. */
+/**
+ * The child receives the configured root and destination as literal argv. Existing roots retain
+ * their files; only the process that creates a root writes its self-ignoring .gitignore.
+ */
+export declare const PREPARE_DIRECTORY = "\nimport fs from 'node:fs/promises';\nimport path from 'node:path';\nasync function main() {\n  const [root, destination] = process.argv.slice(1);\n  await fs.mkdir(path.dirname(root), { recursive: true });\n  let created = false;\n  try {\n    await fs.mkdir(root);\n    created = true;\n  } catch (error) {\n    if (error.code !== 'EEXIST' || !(await fs.stat(root)).isDirectory()) throw error;\n  }\n  if (created) await fs.writeFile(path.join(root, '.gitignore'), '*\\n', { flag: 'wx' });\n  await fs.mkdir(path.dirname(destination), { recursive: true });\n  await fs.mkdir(destination);\n}\nmain().catch(error => { console.error(error.message); process.exitCode = 1; });\n";
+//# sourceMappingURL=directory.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,54 @@
+/** Creates a new Git branch and checkout, then changes the calling Session's working directory. */
+import { Context, Service } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { CreatedWorktree, CreateWorktreeRequest } from './types.ts';
+export type { CreatedWorktree, CreateWorktreeRequest } from './types.ts';
+/** Worktree location, generated names, executables, and subprocess resource limits. */
+export interface Config {
+    /** Relative checkout pool inside the source repository. */
+    directory?: string;
+    /** Prefix for automatically generated branch and checkout names. */
+    namePrefix?: string;
+    /** Executable name or absolute execution-world path of a Git release that honors `GIT_NO_LAZY_FETCH`. */
+    gitCommand?: string;
+    /** Node executable used for sandboxed directory allocation. */
+    nodeCommand?: string;
+    /** Deadline in milliseconds for one command. */
+    timeoutMs?: number;
+    /** Subprocess termination grace in milliseconds. */
+    graceMs?: number;
+    /** Maximum captured bytes per subprocess output stream. */
+    maxOutputBytes?: number;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        worktrees: WorktreeService;
+    }
+}
+/** Creates retained Git worktrees under the mounted filesystem and sandbox providers. */
+export declare class WorktreeService extends Service {
+    static inject: string[];
+    static Config: z<Config>;
+    private readonly config;
+    private readonly lifetime;
+    private readonly pending;
+    constructor(ctx: Context, config: Config);
+    /**
+     * Create a fresh branch and checkout at a pinned local revision, then enter it.
+     * Existing branches or checkout paths fail. Uncommitted files stay in the source checkout.
+     * Checkout disables configured clean, smudge, and process filters without changing Git config.
+     * Repository-local replacement refs still apply; baseCommit reports the resolved object name.
+     * The new checkout becomes current only after Git setup succeeds. Failures may retain newly
+     * allocated Git/filesystem artifacts; no branch or checkout is removed automatically.
+     * @param agent - caller whose current directory selects the source repository and file policy.
+     * @param request - optional new name and local revision; defaults are generated name and HEAD.
+     * @param signal - cancellation of lookup, creation, and working-directory publication.
+     * @returns canonical checkout path, branch name, pinned commit, and source repository root.
+     */
+    create(agent: Agent, request?: CreateWorktreeRequest, signal?: AbortSignal): Promise<CreatedWorktree>;
+    private resolve;
+    private createCheckout;
+}
+export default WorktreeService;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/process.d.ts

@@ -0,0 +1,29 @@
+/** Bounded, cancellable commands under the calling Session's existing file policy. */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SandboxExecutionPolicy } from '@deepseek-ai/dsh-sandbox';
+/** Resolved process resource limits owned by the worktree service. */
+export interface ProcessConfig {
+    /** Deadline for one command, including executable lookup and confinement. */
+    timeoutMs: number;
+    /** Termination grace period for each managed subprocess. */
+    graceMs: number;
+    /** Maximum captured bytes per output stream. */
+    maxOutputBytes: number;
+}
+/**
+ * Run an argv without a shell and await termination of its managed process range.
+ * @param ctx - subprocess and sandbox providers in the same execution world.
+ * @param config - complete process resource limits.
+ * @param policy - unchanged calling Session policy.
+ * @param cwd - canonical process working directory.
+ * @param argv - executable followed by literal arguments.
+ * @param signal - operation cancellation.
+ * @param allowedExitCodes - command-specific successful statuses.
+ * @param env - command-local environment overrides, applied after Git selector removal.
+ * @returns complete bounded stdout and the exit code.
+ */
+export declare function runCommand(ctx: Context, config: ProcessConfig, policy: SandboxExecutionPolicy, cwd: string, argv: readonly [string, ...string[]], signal: AbortSignal, allowedExitCodes?: readonly number[], env?: NodeJS.ProcessEnv): Promise<{
+    stdout: string;
+    exitCode: number;
+}>;
+//# sourceMappingURL=process.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,20 @@
+/** Public requests and results for creating a Git worktree and entering it. */
+/** A new checkout from a locally available Git commit, branch, or tag. */
+export interface CreateWorktreeRequest {
+    /** New branch name, also used as the relative checkout directory; omission generates a name. */
+    name?: string;
+    /** Local revision to resolve before creation; omission selects HEAD. */
+    from?: string;
+}
+/** Committed Git baseline and the calling Session's resulting working directory. */
+export interface CreatedWorktree {
+    /** Canonical absolute checkout directory in the filesystem provider's execution world. */
+    path: string;
+    /** Newly created branch name. */
+    branch: string;
+    /** Resolved commit object name; repository-local replacement refs can change its checked-out content. */
+    baseCommit: string;
+    /** Canonical root of the source checkout. */
+    repositoryRoot: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@deepseek-ai/dsh-experimental-worktree",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Creates a named Git worktree and changes the calling Session working directory",
+  "version": "0.2.1-alpha.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/experimental/worktree"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "~3.18.5-alpha.2",
+    "@deepseek-ai/dsh-timeout": "0.2.1-alpha.3"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.5-alpha.2",
+    "@deepseek-ai/dsh-agent": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-fs": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-sandbox": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-sandbox-policy": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-subprocess": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-working-directory": "0.2.1-alpha.3"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "~4.0.5-alpha.2",
+    "@deepseek-ai/dsh-agent": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-agent-loop-testkit": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-fs": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-fs-local": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-sandbox": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-sandbox-local": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-sandbox-policy": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-session": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-session-projection": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-subprocess": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-subprocess-local": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-system-prompt": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-working-directory": "0.2.1-alpha.3"
+  }
 }