dsh-plugin-worktrees 0.1.0

package/README.zh.md

@@ -0,0 +1,151 @@
+# dsh-worktrees
+
+[English](README.md) | **简体中文**
+
+> 适用于 DeepSeek Harness (dsh) `0.1.0-rc.6` / `0.1.0-rc.7` · Node ≥ 18 · PATH 上有 git · MIT
+
+**让多个 agent 并行写代码而互不打架。** 每个任务拿到自己的目录 —— 一个挂在独立分支上的 git worktree —— 多个 agent 可以同时改代码而互不干扰。任务完成后，其分支经串行队列**一次一个**地合回可供审查的集成分支。如果两个任务改了同几行，冲突现场会原样保留给你 —— 绝不自动解决、绝不强推。
+
+六件工具、零宿主补丁、不接管任何工具名 —— 装上即对所有会话可见 `worktree_*` 工具族。
+
+## 为什么需要它
+
+并行派几个带写权限的子代理，它们会互相踩脚：大家改的是同一个工作目录，每个文件都是一场竞态。经典解法就是 git worktree —— 本插件把它变成 agent 工作流里顺手的一步：
+
+- `worktree_create("api-types")` → 在 `~/.dsh/worktrees/<repo>/<session>/api-types` 得到一个全新检出，分支 `dsh-wt/<session>/<api-types>`。
+- 用 `cwd` 把 agent 派进去（借助
+  [dsh-plugin-subagents](https://github.com/Luck9Star/dsh-plugin-subagents)）—— 你自己进去改也行。
+- `worktree_merge(id)` → 未提交的改动自动提交，然后分支合入 `dsh-wt/integration/<session>` —— 严格一次一个合并，集成之间不会互相撞车。
+
+## 安装
+
+```sh
+# 1. 安装进 dsh profile
+dsh plugin --profile web add dsh-plugin-worktrees   # 或者：add /path/to/本地检出
+
+# 2. 重启并开一个新会话
+dsh --profile web
+```
+
+**预期结果：** 新会话里出现 `worktree_create`、`worktree_list`、`worktree_status`、`worktree_merge`、`worktree_queue`、`worktree_cleanup` 六个工具。
+
+> **用本地检出而不是 npm？** 先在仓库里跑 `npm install && npm run setup:peer`（避免出现第二份 dsh-tools，否则每次工具调用都会崩），再 `dsh plugin --profile web add "$(pwd)"`。
+
+> **想让 agent 直接在 worktree 里干活？** 官方宿主会静默丢弃子代理的 `cwd`。安装
+> [dsh-plugin-subagents](https://github.com/Luck9Star/dsh-plugin-subagents)
+> 并跑它的 `patches/install.sh`（每次 dsh 升级后重跑）。
+
+## 快速上手
+
+完整闭环 —— 两个并行任务、一次干净合并、一次冲突：
+
+```jsonc
+worktree_create({ task: "api-types" })    // → { id: id1, path: P1, branch, base_commit, … }
+worktree_create({ task: "docs-refresh" }) // → { id: id2, path: P2, … }
+
+// 并行干活 —— 每个 agent（或你自己）在自己的 path 里改
+subagent({ prompt: "实现新的 API 类型。", cwd: P1 })
+subagent({ prompt: "刷新文档。",         cwd: P2 })
+
+worktree_merge({ worktree_id: id1 })
+// → { state: "succeeded", integrated_commit, integration_branch }
+
+worktree_merge({ worktree_id: id2 })
+// → { state: "conflicted", conflict_files: [...],
+//     integration_worktree: "<保留的现场>", resolution_hint: "…" }
+
+// 在保留的 worktree 里手工解决（冲突标记都在），然后：
+worktree_queue({ action: "list" })
+worktree_queue({ action: "resolve", job_id: "…" })   // 释放集成分支
+worktree_cleanup({ worktree_id: id1 })               // 移除 worktree 和分支
+```
+
+## 六个工具
+
+| 工具 | 作用 |
+| --- | --- |
+| `worktree_create` | 为任务新建 worktree + 专属分支。返回 `path`（直接交给 `cwd`）、`branch`、`base_commit`、`integration_branch`。 |
+| `worktree_list` | 列出某仓库的 worktree（可选包含保留的冲突现场），附合并队列摘要。 |
+| `worktree_status` | 单个 worktree：HEAD、脏状态、逐文件变更、领先基线多少、当前合并作业。 |
+| `worktree_merge` | 自动提交未提交改动，然后入队并合入集成分支。五种可能结果（见下）。 |
+| `worktree_queue` | 查看队列；对作业 `resolve` / `retry` / `cancel`。 |
+| `worktree_cleanup` | 移除 worktree（及分支，除非 `keep_branch`）。未经双重确认，拒绝销毁未合并的工作。 |
+
+### 合并结果
+
+| `state` | 含义 |
+| --- | --- |
+| `succeeded` | 合并成功；集成分支上出现 `integrated_commit`。 |
+| `conflicted` | 有冲突。集成 worktree 连同冲突标记**保留**；该作业占住集成分支，直到你 `resolve` 或 `retry`。 |
+| `queued` | 排在其他合并后面（`queued_ahead` 告诉你前面有几个）。 |
+| `no_changes` | 工作树相对基线是干净的 —— 无可集成（正常，不是错误）。 |
+| `failed` | 硬失败（如 `autoCollect: false` 时工作树脏 → `dirty_not_collected`）。 |
+
+### 冲突处理，一句话版
+
+不自动解决、不 rebase、不强推。冲突的合并保留现场（一个带冲突标记的 worktree），列出冲突文件，并**占住集成分支**，直到你：在保留的 worktree 里改完文件后 `worktree_queue(action: "resolve")`；或 `action: "retry"` 重新排队；或放弃。
+
+## 内建的安全机制
+
+- **未合并的工作很难丢。** 清理一个提交还没进集成分支的 worktree，需要**两**个独立确认（`force: true` **且** `acknowledge: true`），否则带证据拒绝。已合并的 worktree 直接清理，没有仪式。
+- **仓库门禁，从严失败。** 只在会话 cwd 子树、已注册工作区或 `allowedRoots` 里建 worktree —— 没有"任意根"开关。分支名由 git 本身校验。
+- **只在本地。** 插件会合并，但绝不 push/fetch/clone —— 结果留在本地集成分支上，等人审查后再推。
+- **脏工作树有归宿。** `autoCollect: true`（默认）在合并前自动提交未提交改动（含未跟踪文件）。关掉它，脏树会以明确报错拦下合并，而不是硬来。
+- **重启安全。** 启动时，仓库/路径已消失的 worktree 标记为 `orphaned`，在途合并判失败并附说明 —— 只做标记，不做破坏性删除。
+
+## 配置
+
+全部可选 —— 下表每项都有可用默认值。配置写在 profile 的 `cordis.patch.yml` 中本插件的行上；写错的键会在启动时大声报错。
+
+| 键 | 默认值 | 含义 |
+| --- | --- | --- |
+| `worktreeRoot` | `~/.dsh/worktrees/` | 所有任务 worktree 的根目录。 |
+| `maxWorktrees` | `16` | 跨仓库的非终态 worktree 上限。 |
+| `defaultBaseRef` | `HEAD` | 新任务分支的起点（总是解析成具体 commit）。 |
+| `autoCollect` | `true` | 合并前自动提交未提交改动。 |
+| `gitTimeoutMs` / `mergeTimeoutMs` | `15000` / `120000` | 单条 git 命令 / 合并步骤的超时。 |
+| `allowedRoots` | `[]` | 门禁额外放行的仓库根。 |
+| `requireWorkspaceRegistration` | `true` | 同时放行已注册工作区（关闭后仅靠会话 cwd + `allowedRoots`）。 |
+| `statePath` | `~/.dsh/dsh-worktrees/state.json` | 状态文件（原子写、仅所有者）。 |
+| `retainJobHistory` | `200` | 保留的终态合并作业记录数。 |
+| `register.*` | `true` | 按工具注册开关。 |
+
+## 搭配使用
+
+- [dsh-plugin-subagents](https://github.com/Luck9Star/dsh-plugin-subagents)
+  —— 它的逐次调用 `cwd` 就是接合点：把 `worktree_create` 返回的 `path` 直接交给子代理，它就写进 worktree。
+- [dsh-dag-orchestrator](https://github.com/Luck9Star/dsh-dag-orchestrator)
+  —— 本插件对外暴露 `worktreesEngine` 服务，编排器探测到即可用，DAG 里的 `worktree:` 任务隔离与 `merge` 节点零接线开启。
+
+## 边界与常见问题
+
+- **一个仓库的合并只走一个 dsh 会话。** 队列是进程内的；不支持两个宿主并发合并同一仓库。
+- **`cwd` 被忽略了？** 官方宿主会丢弃它 —— 装 dsh-plugin-subagents 并跑它的 `patches/install.sh`。
+- **`active_job_exists` 报错** —— 更早的一个冲突作业占着集成分支；`worktree_queue(action: "list")`，然后 `resolve` 或 `retry` 它。
+- **每次工具调用都报 `Cannot read properties of undefined (reading 'prepare')`** —— 本地检出没跑 `npm run setup:peer`；在本仓库 `npm install` 后、或 dsh 升级后重跑。
+
+## 开发
+
+```sh
+npm install && npm run setup:peer   # 链接正在运行的宿主的 peers
+npm test                            # node --test，真实本地 git 夹具 —— 不碰网络与远端
+npm run lint
+```
+
+设计记录：[docs/DESIGN.md](docs/DESIGN.md)。
+
+## 参考与致谢
+
+- **git worktree** —— 这一切所构建的底层机制。
+- **task-weaver**（`packages/workspaces/`）—— 核心引擎（git 端口、合并队列、冲突现场保留）移植自它。
+- [dsh-plugin-subagents](https://github.com/Luck9Star/dsh-plugin-subagents)
+  与 [dsh-dag-orchestrator](https://github.com/Luck9Star/dsh-dag-orchestrator)
+  —— 为组合而生的伙伴插件。
+
+## 安全
+
+见 [SECURITY.md](SECURITY.md)。
+
+## 许可证
+
+[MIT](LICENSE)

package/SECURITY.md

@@ -0,0 +1,56 @@
+# Security
+
+This plugin drives **local git repositories only**. Please read this before
+deploying it.
+
+## What the plugin does
+
+- **No network operations — by construction.** Every git call goes through
+  `lib/git-port.js`, whose interface has no `push`, `fetch`, or `clone`
+  method at all. The plugin cannot reach a remote even by accident;
+  integration results stay on the local integration branch for a human to
+  review and push. Each git invocation also sets `GIT_TERMINAL_PROMPT=0`,
+  so git never prompts for credentials interactively.
+- **No credential handling.** The plugin reads no secrets, stores no
+  secrets, and passes no credentials anywhere. Git subprocesses inherit the
+  parent environment (plus `GIT_TERMINAL_PROMPT=0`); do not rely on the
+  plugin to scrub anything from it.
+- **Command-injection resistant.** Git is spawned as
+  `spawn("git", argvArray, {shell: false})` — argv is never a shell string.
+  Caller-controllable refs are resolved with
+  `rev-parse --verify --end-of-options`, branch names (task slugs AND
+  explicitly supplied integration branches — including the merge-time
+  override and the engine-seam enqueue, re-vetted at apply time) are
+  pre-vetted with `check-ref-format --branch`, and positional refs sit
+  after the `--` end-of-options terminator (`scripts/lint.js` enforces the
+  single-ingress rule statically: only `git-port.js` may spawn).
+- **Repo admission fails closed.** A repository root is only admitted after
+  realpath canonicalisation when it lives inside the session-cwd subtree, a
+  registered workspace, or an explicitly configured `allowedRoots` entry —
+  there is no any-root switch.
+- **Destructive actions are gated.** Deleting unmerged work requires the
+  double confirmation `force: true` AND `acknowledge: true` — "unmerged"
+  covers BOTH the task branch not having reached the integration branch
+  AND the integration branch not existing yet while the worktree holds
+  commits past its base (work that exists nowhere else). With
+  `autoCollect: false` a dirty worktree is never silently skipped: the
+  merge fails `dirty_not_collected` instead of reporting success over
+  unintegrated files. Conflicted merge scenes (worktree + source branch)
+  are retained until explicitly cleaned up; startup crash reconciliation
+  marks and never destroys.
+
+## What to keep private
+
+- The state file (default `~/.dsh/dsh-worktrees/state.json`) records repo
+  paths, branch names, and merge-job history. It is written atomically with
+  owner-only `0600` permissions and a `__proto__`-key guard. Treat it as
+  private runtime state and never commit it.
+- Worktrees created under `~/.dsh/worktrees/` contain full copies of your
+  repositories' working trees — the same sensitivity as the repositories
+  themselves.
+
+## Reporting
+
+Report vulnerabilities via GitHub Issues on this repository's tracker
+(placeholder until a private channel is set up). Do not open public issues
+for exploitable flaws if a private channel is available to you.

package/cordis.patch.yml

@@ -0,0 +1,30 @@
+# dsh-worktrees bundle patch (T11, DESIGN §8.3).
+#
+# 用途：把 dsh-worktrees 插件实例挂进 profile 的层序。本插件是纯 tool
+#   插件——六件工具（worktree_create / list / status / merge / queue /
+#   cleanup）全部是新名字，注册在全局工具层，对所有会话天然可见：
+#   无需 disable 任何官方行（不接管官方工具名）、无需 preset 适配、
+#   零宿主补丁（本仓库没有 patches/ 目录）。形态对齐 dsh-ssh 的单
+#   insert 写法。
+#
+# 安装方式：`dsh plugin --profile <name> add dsh-worktrees`（或 add
+#   <本地路径>）——reconcile 解析 package.json 的 dsh.bundle.patch 字段，
+#   自动把本 patch 层追加到 bundles 尾部，insert 行随即生效。之后在本
+#   仓库跑 `npm run setup:peer`（dsh-tools 单实例 symlink，peer 纪律见
+#   README），再重启 dsh 开新会话。要覆盖配置，在 profile 层同 id 行
+#   写 config（profile 层覆盖 bundle 层），键表见 README「配置」。
+#
+# 互斥：无。新名字工具不与官方行或同族插件冲突，可与 dsh-plugin-
+#   subagents 等任意 bundle 并存（正交组合正是本插件的卖点）。
+
+- insert:
+    # 本行即 host-plane Cordis 插件实例；六件 worktree_* 工具由它注册。
+    - id: worktrees
+      name: dsh-worktrees
+      config:
+        # —— 全部键省略即走 lib/config.js 的 zod strict 默认；示例（注释）：
+        # maxWorktrees: 16                     # 非终态 worktree 全局上限（跨 repo 计数）
+        # allowedRoots: ["~/Documents/dev/Agents"]  # repo 门禁额外放行的根（realpath 子树判定）
+        # 其余键：worktreeRoot / statePath / defaultBaseRef / gitTimeoutMs /
+        # mergeTimeoutMs / requireWorkspaceRegistration / autoCollect /
+        # retainJobHistory / register 六开关 —— 逐键说明见 README。