dsh-plugin-worktrees 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -5,6 +5,48 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.2] - 2026-08-27
+
+Fixes for the two load-failure issues reported against 0.1.1. **Upgrade is
+required for npm-based installs** — 0.1.x cannot load at all from an
+`dsh plugin add dsh-plugin-worktrees` install.
+
+### Fixed
+
+- **npm installs: plugin tree failed to load with `ERR_MODULE_NOT_FOUND`
+  (issue #1).** The patch entry in `cordis.patch.yml` said `name:
+  dsh-worktrees` (the repo name) while the npm package is
+  `dsh-plugin-worktrees`; the cordis loader imports the entry's `name` as a
+  module specifier against the profile's node_modules, so every npm-based
+  install died. The patch `name`, `package.json` name, and the module's
+  `export const name` are now identical (family convention), and
+  `test/cordis-patch.test.js` pins the invariant so the drift cannot
+  silently return.
+- **`config:` parsing to null rejected by zod strict (issue #2).** A patch
+  `config:` key holding only comments parses as YAML `null`;
+  `validateConfig` now treats `null`/`undefined` as "no configuration" and
+  applies defaults instead of failing with `(root): Expected object,
+  received null`. The shipped patch uses an explicit `config: {}`. Other
+  non-object shapes (e.g. an array) still fail loudly with a precise root
+  message.
+- **Source-tree (tsx) launcher: dual-instance self-check misfired fatally
+  (issue #2).** Under `pnpm dsh web` the harness resolves `dsh-tools` to its
+  src build while the plugin gets the lib build — two module instances, two
+  `TOOL_RUNTIME_SCHEDULER` Symbols — and `assertSingleDshToolsInstance`'s
+  fatal branch killed the boot even though the plugin works fine (its tools
+  only use the public `ctx.tools.register` API and never touch the Symbol).
+  The check is now an advisory warning naming the `setup:peer` escape hatch;
+  `npm run setup:peer` remains the fix for a genuine second copy whose tool
+  calls do fail with `Cannot read properties of undefined (reading
+  'prepare')`.
+
+### Tests
+
+- 295 → 310: new `test/cordis-patch.test.js` (patch/name/config shape
+  guard), null-config and missing-config boot coverage, array-config
+  failure coverage, and the softened self-check branches re-pinned (Symbol
+  split now expects warn + full six-tool registration instead of a throw).
+
 ## [0.1.1] - 2026-08-18
 
 First release through the npm trusted-publishing pipeline (OIDC, tag

package/README.md

@@ -44,8 +44,17 @@ dsh --profile web
 **Expected result:** a new session exposes `worktree_create`, `worktree_list`,
 `worktree_status`, `worktree_merge`, `worktree_queue`, `worktree_cleanup`.
 
+> **Both launchers work (0.1.2).** The dual-instance check that 0.1.x turned
+> into a hard failure is now an advisory warning: under the source-tree (tsx)
+> launcher the harness loads the `src` build of `dsh-tools` while the plugin
+> gets the `lib` build, which used to kill the boot with a false positive.
+> This plugin only uses the public `ctx.tools.register` API, so the two
+> copies coexist safely; the warning points at `setup:peer` for the rare case
+> where tool calls DO fail with `Cannot read properties of undefined
+> (reading 'prepare')`.
+
 > **Local checkout instead of npm?** Run `npm install && npm run setup:peer`
-> inside the repo first (avoids a second copy of `dsh-tools`, which crashes
+> inside the repo first (avoids a second copy of `dsh-tools`, which can crash
 > every tool call), then `dsh plugin --profile web add "$(pwd)"`.
 
 > **Want agents to work inside the worktrees?** The stock harness silently
@@ -163,8 +172,10 @@ row in your profile's `cordis.patch.yml`; unknown keys fail loudly at startup.
   integration branch; `worktree_queue(action: "list")`, then `resolve` or
   `retry` it.
 - **Every tool call dies with `Cannot read properties of undefined
-  (reading 'prepare')`** — local checkout without `npm run setup:peer`;
-  re-run it after `npm install` here or a dsh upgrade.
+  (reading 'prepare')`** — a genuine second `dsh-tools` copy (typically a
+  local checkout without `npm run setup:peer`); re-run it after `npm
+  install` here or a dsh upgrade. A startup *warning* alone is expected and
+  harmless — see the note under Install.
 
 ## Development
 

package/README.zh.md

@@ -29,7 +29,9 @@ 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)"`。
+> **两种启动方式都支持（0.1.2 起）。** 0.1.x 曾把 dsh-tools 双实例检查做成硬失败，现在是建议性告警：源码树（tsx）启动器下宿主加载 dsh-tools 的 `src` 构建、插件拿到 `lib` 构建，旧版会被这个假阳性直接卡死启动。本插件只用公开的 `ctx.tools.register` API，两份拷贝可以安全共存；告警里指明的 `setup:peer` 只在工具调用真的报 `Cannot read properties of undefined (reading 'prepare')` 时才需要跑。
+
+> **用本地检出而不是 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)
@@ -122,7 +124,7 @@ worktree_cleanup({ worktree_id: id1 })               // 移除 worktree 和分
 - **一个仓库的合并只走一个 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 升级后重跑。
+- **每次工具调用都报 `Cannot read properties of undefined (reading 'prepare')`** —— 真正的第二份 dsh-tools 拷贝（典型：本地检出没跑 `npm run setup:peer`）；在本仓库 `npm install` 后、或 dsh 升级后重跑。仅启动时出现一条*告警*是预期且无害的 —— 见「安装」下的说明。
 
 ## 开发
 

package/cordis.patch.yml

@@ -1,4 +1,4 @@
-# dsh-worktrees bundle patch (T11, DESIGN §8.3).
+# dsh-plugin-worktrees bundle patch (T11, DESIGN §8.3).
 #
 # 用途：把 dsh-worktrees 插件实例挂进 profile 的层序。本插件是纯 tool
 #   插件——六件工具（worktree_create / list / status / merge / queue /
@@ -7,24 +7,31 @@
 #   零宿主补丁（本仓库没有 patches/ 目录）。形态对齐 dsh-ssh 的单
 #   insert 写法。
 #
-# 安装方式：`dsh plugin --profile <name> add dsh-worktrees`（或 add
+# 安装方式：`dsh plugin --profile <name> add dsh-plugin-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「配置」。
+#   自动把本 patch 层追加到 bundles 尾部，insert 行随即生效。
+#
+# 两条曾经踩过的坑（0.1.2 修复，勿回退）：
+#   1. name 必须等于 npm 包名（package.json 的 name）——loader 拿这个
+#      字段作为 import specifier 去 profile 的 node_modules 解析；写成
+#      仓库名 dsh-worktrees 会让整个插件树 ERR_MODULE_NOT_FOUND（issue #1）。
+#      test/cordis-patch.test.js 钉死 patch name === package.json name。
+#   2. config 必须是显式的 `{}` —— 只跟注释的裸 `config:` 键会被 YAML
+#      解析成 null，zod strict 拒收（issue #2）。要覆盖配置，请在
+#      profile 层的同 id 行写 config（profile 层覆盖 bundle 层），键表见
+#      README「配置」：
+#        maxWorktrees: 16                          # 非终态 worktree 全局上限（跨 repo 计数）
+#        allowedRoots: ["~/Documents/dev/Agents"]  # repo 门禁额外放行的根（realpath 子树判定）
+#        其余键：worktreeRoot / statePath / defaultBaseRef / gitTimeoutMs /
+#        mergeTimeoutMs / requireWorkspaceRegistration / autoCollect /
+#        retainJobHistory / register 六开关 —— 逐键说明见 README。
 #
 # 互斥：无。新名字工具不与官方行或同族插件冲突，可与 dsh-plugin-
 #   subagents 等任意 bundle 并存（正交组合正是本插件的卖点）。
 
 - insert:
     # 本行即 host-plane Cordis 插件实例；六件 worktree_* 工具由它注册。
+    # config 显式空表 = lib/config.js 的 zod strict 全默认。
     - 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。
+      name: dsh-plugin-worktrees
+      config: {}

package/docs/DESIGN.md

@@ -628,22 +628,26 @@ dsh-worktrees/
 ### 8.3 cordis.patch.yml（形态）
 
 ```yaml
-# dsh-worktrees bundle patch — 单行 insert（新名字工具在全局层天然可见，
+# dsh-plugin-worktrees bundle patch — 单行 insert（新名字工具在全局层天然可见，
 # 无需 disable 任何官方行；对齐 dsh-ssh 的单 insert 形态）。
 - insert:
     - id: worktrees
-      name: dsh-worktrees
-      config:
-        # 全部键省略走 lib/config.js 默认；示例：
-        # maxWorktrees: 16
-        # allowedRoots: ["~/Documents/dev/Agents"]
+      name: dsh-plugin-worktrees
+      config: {}
 ```
 
-insert 行写法学自：dsh-ssh `cordis.patch.yml`（单 insert 双面插件）与 dsh-web-ui-all 聚合 patch（`- insert:` + `- id:` + `name:` 两键缩进形态）。`dsh plugin --profile <name> add dsh-worktrees` 后 reconcile 自动追加层序（分析 §4：解析 `dsh.bundle.patch` 依赖按序追加 bundles 尾部）。
+insert 行写法学自：dsh-ssh `cordis.patch.yml`（单 insert 双面插件）与 dsh-web-ui-all 聚合 patch（`- insert:` + `- id:` + `name:` 两键缩进形态）。`dsh plugin --profile <name> add dsh-plugin-worktrees` 后 reconcile 自动追加层序（分析 §4：解析 `dsh.bundle.patch` 依赖按序追加 bundles 尾部）。
 
-### 8.4 peer 双实例防御（C6）
+**0.1.2 修订（issue #1 + #2，两条都是这个文件的 drift，已由 `test/cordis-patch.test.js` 钉死）：**
 
-`@deepseek-ai/dsh-tools` 声明 peer；README 安装步骤含 `npm run setup:peer`（symlink 到 live harness 根，脚本照搬 subagents `scripts/link-harness-dsh-tools.sh` 模式）；`apply()` 开头做 subagents 同款 `assertSingleDshToolsInstance` 自检（`TOOL_RUNTIME_SCHEDULER` Symbol 探测，失败即 logger.fatal + throw —— 分析 §4-C6 的既证失效面）。
+1. **`name` 必须等于 npm 包名**（package.json 的 `name`）。cordis loader 拿 entry 的 `name` 作为 import specifier 去 profile 的 node_modules 解析（`cordis-plugin-loader` `_init()` 的 `tree.import(this.options.name, …)`）——0.1.x 写成仓库名 `dsh-worktrees` 而 npm 发的是 `dsh-plugin-worktrees`，所有 npm 安装路径死于 `ERR_MODULE_NOT_FOUND`。家族惯例（dsh-plugin-subagents）三名一致：package name === patch name === 模块导出 `export const name`。
+2. **`config` 必须显式写 `{}`**。只跟注释的裸 `config:` 键被 YAML 解析成 `null`，zod strict 报 `(root): Expected object, received null`（宿主把 entry config 原样传进 apply()）。注释示例移到文件头注释，行内只留空表；`lib/config.js` 同时对 null 走默认值兜底（双保险）。
+
+### 8.4 peer 双实例防御（C6）—— 0.1.2 起为建议性告警
+
+`@deepseek-ai/dsh-tools` 声明 peer；README 安装步骤含 `npm run setup:peer`（symlink 到 live harness 根，脚本照搬 subagents `scripts/link-harness-dsh-tools.sh` 模式）；`apply()` 开头保留 subagents 同款 `assertSingleDshToolsInstance` 探测（`TOOL_RUNTIME_SCHEDULER` Symbol）。
+
+**0.1.2 修订（issue #2）：分支 2（Symbol 缺失 + ToolRuntime 形状 ⇒ fatal + throw）软化为 warn + 继续注册。** 原设计照搬 dsh-plugin-subagents，但在源码树（tsx）启动器下必然误杀：宿主经 tsconfig paths 把 `@deepseek-ai/dsh-tools` 解析到 **src 构建**，插件经普通 ESM 从 profile node_modules 解析到 **lib 构建** —— 两个物理实例、两个 Symbol，`setup:peer` 的 symlink 只能指向 lib 构建、无法统一。软化是安全的：本插件六件工具全部经公开 `ctx.tools.register` API 注册、用 `defineTool` 纯定义对象，工具体从不触碰 scheduler Symbol（该 Symbol 由 dsh-agent-loop 消费、且永远作用于宿主自己的 dsh-tools 实例）——双实例对本插件无功能影响。告警文案保留 `setup:peer` 提示，覆盖真正双实例（工具调用报 `Cannot read properties of undefined (reading 'prepare')`）的场景。
 
 ---
 

package/lib/config.js

@@ -101,6 +101,15 @@ export const SCALAR_DEFAULTS = Object.freeze({
  *   clear message)
  */
 export function validateConfig(config = {}) {
+  // A comment-only `config:` key in a host YAML layer parses as null (issue
+  // #2) — an absent configuration, not an invalid one, so it takes the same
+  // defaults path as an omitted key. Any other non-object still fails loud.
+  if (config === null || config === undefined) config = {}
+  if (typeof config !== 'object' || Array.isArray(config)) {
+    throw new Error(
+      `dsh-worktrees: invalid config — (root): expected an object, got ${Array.isArray(config) ? 'array' : typeof config}`,
+    )
+  }
   const result = pluginConfigSchema.safeParse(config)
   if (!result.success) {
     const issues = result.error.issues.map(

package/lib/index.js

@@ -9,14 +9,15 @@
  * apply() order (DESIGN §3 diagram + §7.3 "before tool registration"):
  *
  *   a. validateConfig (lib/config.js zod strict; unknown keys fail loud);
- *   b. assertSingleDshToolsInstance — the @deepseek-ai/dsh-tools dual-
- *      instance self-check (§8.4, pattern carried over verbatim from
- *      dsh-plugin-subagents lib/index.js): the host ToolRuntime carries its
- *      scheduler under the dsh-tools module-level TOOL_RUNTIME_SCHEDULER
- *      Symbol; a second physical copy of the package makes
- *      `ctx.tools[Symbol]` undefined and every tool call dies with
- *      "Cannot read properties of undefined (reading 'prepare')" — fatal at
- *      apply time, with the setup:peer re-link hint;
+ *   b. assertSingleDshToolsInstance — the @deepseek-ai/dsh-tools
+ *      dual-instance ADVISORY probe (§8.4, softened at 0.1.2 per issue #2):
+ *      the host ToolRuntime carries its scheduler under the dsh-tools
+ *      module-level TOOL_RUNTIME_SCHEDULER Symbol; when that Symbol is not
+ *      visible on ctx.tools (a second physical copy of the package, or the
+ *      src/lib split under the source-tree tsx launcher) the probe warns
+ *      with the setup:peer hint and lets the boot continue — this plugin
+ *      only uses the public ctx.tools.register API, so a split instance
+ *      cannot break its tool calls (see the function comment for history);
  *   c. createGitPort (timeoutMs = gitTimeoutMs) + createStateStore +
  *      store.load() (a corrupt state file aborts the boot loudly);
  *   d. reconcile — the crash reconciliation (§7.3), BEFORE any tool is
@@ -59,7 +60,13 @@ import { registerWorktreeMergeTool } from './tools/worktree-merge.js'
 import { registerWorktreeQueueTool } from './tools/worktree-queue.js'
 import { registerWorktreeCleanupTool } from './tools/worktree-cleanup.js'
 
-export const name = 'dsh-worktrees'
+// Plugin identity must equal the npm package name (package.json "name"):
+// the cordis loader resolves the patch entry's `name` as an import specifier
+// against the profile's node_modules, and the family convention (dsh-plugin-
+// subagents) keeps package name === patch name === module export name. The
+// 0.1.x drift (patch said `dsh-worktrees`, npm said `dsh-plugin-worktrees`)
+// broke every npm-based install with ERR_MODULE_NOT_FOUND (issue #1).
+export const name = 'dsh-plugin-worktrees'
 
 // workspaceRegistry is used through OPTIONAL probing (§8.2 peer-face
 // minimisation: headless hosts without a workspace registry still boot) —
@@ -81,38 +88,42 @@ function realPathBestEffort(target) {
 }
 
 /**
- * dsh-tools dual-instance self-check (§8.4; the verbatim probe pattern from
- * dsh-plugin-subagents lib/index.js):
+ * dsh-tools dual-instance advisory probe (§8.4; softened at 0.1.2, issue #2).
+ *
+ * History: this used to be a fatal check modelled on dsh-plugin-subagents —
+ * Symbol absent + ToolRuntime shape ⇒ throw. That misfires under the
+ * source-tree (tsx) harness launcher: the harness resolves dsh-tools to its
+ * src build (via tsconfig path mappings) while the plugin, loaded from the
+ * profile's node_modules by plain ESM, gets the lib build — two PHYSICAL
+ * module instances, two Symbols, and `npm run setup:peer` cannot unify them
+ * (its symlink points at the lib build only). The fatal then made the plugin
+ * outright unusable there.
+ *
+ * Why softening is safe: every tool this plugin registers goes through the
+ * PUBLIC `ctx.tools.register` API and plain `defineTool` definition objects.
+ * The tool bodies never touch the scheduler Symbol — that Symbol is consumed
+ * by dsh-agent-loop when dispatching the HOST's tools, always against the
+ * host's own dsh-tools instance. A second dsh-tools copy only matters if
+ * plugin code reached for cross-instance identity (ours never does), so a
+ * missing Symbol degrades to a warning that names the diagnostic rule of
+ * thumb, never a load failure.
  *
  *   1. `ctx.tools[TOOL_RUNTIME_SCHEDULER] !== undefined` → same physical
- *      module — healthy;
- *   2. Symbol absent but ctx.tools looks like a real ToolRuntime
- *      (view + schemas) → a true second copy: logger.fatal + throw (apply
- *      failing beats every tool call dying after load), pointing at the
- *      peer re-link (npm run setup:peer);
- *   3. anything else (fake ctx / an unseen host shape) → cannot reliably
- *      judge; warn only. Tests and non-standard hosts must not be killed by
- *      a false positive.
+ *      module — healthy, silent;
+ *   2. Symbol absent (fake ctx, src/lib split, or a true second copy) →
+ *      warn only, keep booting.
  */
 function assertSingleDshToolsInstance(ctx) {
   const tools = ctx && ctx.tools
   if (!tools || typeof tools.register !== 'function') return
   if (tools[TOOL_RUNTIME_SCHEDULER] !== undefined) return // same physical module — healthy
-  const looksLikeToolRuntime =
-    typeof tools.view === 'function' && typeof tools.schemas === 'function'
-  if (looksLikeToolRuntime) {
-    const detail =
-      'dsh-worktrees: detected a second @deepseek-ai/dsh-tools module instance — '
-      + "every tool call from this plugin would die with \"Cannot read properties of undefined (reading 'prepare')\". "
-      + 'Run npm run setup:peer (scripts/link-harness-dsh-tools.sh) in the dsh-worktrees package '
-      + 'so its dsh-tools copy resolves to the live harness root, then restart dsh.'
-    if (ctx.logger && typeof ctx.logger.fatal === 'function') ctx.logger.fatal(detail)
-    throw new Error(detail)
-  }
   if (ctx.logger && typeof ctx.logger.warn === 'function') {
     ctx.logger.warn(
-      'dsh-worktrees: could not reliably verify the @deepseek-ai/dsh-tools single-instance invariant '
-        + 'from this ctx (no scheduler symbol, no ToolRuntime shape) — run npm run setup:peer to check the dedupe link',
+      'dsh-worktrees: the @deepseek-ai/dsh-tools scheduler Symbol is not visible on ctx.tools '
+        + '(a second dsh-tools copy, or the src/lib split under the source-tree tsx launcher). '
+        + "This plugin only uses the public ctx.tools.register API, so tool calls are unaffected; "
+        + 'if you DO see "Cannot read properties of undefined (reading \'prepare\')", run '
+        + 'npm run setup:peer (scripts/link-harness-dsh-tools.sh) in this package and restart dsh.',
     )
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-worktrees",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "git worktree parallel write isolation + serial merge integration plugin for the DeepSeek Harness",
   "type": "module",
   "main": "lib/index.js",