dsh-plugin-worktrees 0.1.0

package/docs/TASKS.md

@@ -0,0 +1,164 @@
+# dsh-worktrees — 实施任务分解
+
+> 配套 `docs/DESIGN.md` 阅读（D 表示其章节，R 表示其 §12 红线）。任务可独立派发给实现代理；每个任务自包含：目标 / 范围与涉及文件 / 验收标准 / 依赖。
+>
+> 通用约束（每个任务默认遵守）：
+> - **唯一 git 出口**：一切 git 经 `lib/git-port.js` argv 数组（R1）；`lib/` 其它模块出现 `spawn(` 即 lint 失败（T12）。
+> - 测试一律 `node:test`；真 git fixture 全本地 `git init`（tmp 目录），**零网络零远端**（R8）；迁移自 task-weaver 的用例不得削弱断言。
+> - 迁移代码（git-port / merge-queue / worktree-service / naming）保持行级等价，仅做 DESIGN 明确要求的改名/收窄/替换；原注释语义保留。
+> - Plain JS ESM；零新增运行时依赖（zod 除外，同家族版本）；`engines >=18`（不用 `Promise.withResolvers`）。
+
+## 阶段总览与依赖图
+
+```
+P0 脚手架      T01
+P1 基础引擎    T02 T03 T04 T05        （T02 先行；T03/T04/T05 依赖 T02，互相独立可并行）
+P2 工作区服务  T06 T07                 （T06 依赖 T02-T05；T07 依赖 T06）
+P3 集成队列    T08 T09                 （T08 依赖 T06；T09 依赖 T08）
+P4 工具面      T10 T11 T12             （T10 依赖 T07+T08；T11/T12 依赖 T10）
+P5 总装与质量  T13 T14 T15             （T13 依赖全部；T14/T15 收尾）
+```
+
+---
+
+## P0 脚手架
+
+### T01 仓库脚手架与包清单
+- **目标**：新仓库可 `npm install && npm test`（空测试）通过，包身份与依赖契约定稿。
+- **范围/文件**：`package.json`（name `dsh-worktrees`；`type: module`；`engines: {node: ">=18"}`；`dsh.bundle.patch: "./cordis.patch.yml"`；deps `zod@^3.23.0`；peerDependencies `@deepseek-ai/{cordis@^4.0.1, dsh-tools@^0.1.0-rc.6}`；scripts test/lint/setup:peer）、`.gitignore`、`LICENSE`（MIT）、`test/.smoke.test.js`、`scripts/link-harness-dsh-tools.sh`（照搬 dsh-plugin-subagents 同名脚本模式：动态解析 live harness 根，禁止硬编码）。
+- **验收**：`npm test` 绿；`dsh.bundle.patch` 字段存在；空 `cordis.patch.yml` 可被 YAML 解析。
+- **依赖**：无。
+
+---
+
+## P1 基础引擎（一切的地基）
+
+### T02 GitPort 直搬（最大单体，先行）
+- **目标**：`lib/git-port.js` 就位 —— task-weaver `git-port.ts` 逐行直搬 + DESIGN §4.1 指定改写。
+- **范围/文件**：`lib/git-port.js`、`test/git-port.test.js`。
+  - 直搬：`runGit`（argv spawn + shell:false + 15s 超时 SIGKILL + 双流独立 8MiB 记账上限 + `[output capped]` 标记）、`parseGitStatusPorcelain`（XY 码 / rename target / y=R / 引号剥离 / `?`→added）、`parseGitNameStatus`（R/C 双 tab / 未知字母→unknown）、`NodeGitPort`（原 `BunGitPort`）：`isGitRepo` / `resolveHead` / `resolveRef`（**`--verify --end-of-options <ref>^{commit}`** 防注入，逐字符照抄）/ `createWorktree` / `removeWorktree`（--force 幂等）/ `commitAll`（add -A → commit → HEAD + name-status）/ `status` / `checkout` / `cherryPick` / `mergeBase` / `listConflicts`（`--diff-filter=U`，非零→空清单）/ `addWorktreeAt` / `ensureBranch`；构造器 `GIT_TERMINAL_PROMPT: "0"`。
+  - 改写：类名 `BunGitPort`→`NodeGitPort`；裁私有 `worktreePath()`（mkdtemp 布局）；导出 `createGitPort({ spawnImpl })` 注入缝（默认 runGit）。
+  - 新增：`listWorktrees`（`worktree list --porcelain` + 新解析函数 `parseWorktreeListPorcelain`：空行分块，worktree/HEAD/branch/detached 字段）、`isAncestor`（`merge-base --is-ancestor` exit 0/1）、`validateBranch`（`check-ref-format --branch`）、`mergeNoFf`（`["merge","--no-ff","--no-edit","-m",msg,"--",branch]`）、`abortMerge`。
+  - 测试：bun:test→node:test 直迁 `git-port.test.ts`（fixture：argv-only git 助手独立于被测 runGit、显式 GIT_AUTHOR_*/COMMITTER_* env、独立 worktree 父目录）+ 新方法用例（porcelain 解析表、isAncestor 两态、validateBranch 拒 `..`/空格/前导 `-`）。
+- **验收**：全部用例绿（本地 git 2.x）；grep 确认无 `shell: true`、无字符串拼接 argv；非零 git 退出不 reject（status 字段语义保留）。
+- **依赖**：T01。
+
+### T03 naming（分支/路径命名，纯函数）
+- **目标**：`lib/naming.js` —— DESIGN §5.2.1。
+- **范围/文件**：`lib/naming.js`、`test/naming.test.js`：`sanitizeBranch`（`[^a-zA-Z0-9_.-]`→`_`，截 48）、`taskBranch(sessionShort, task)` → `dsh-wt/<session>/<task>`、`integrationBranch(sessionShort)`、`worktreePath(worktreeRoot, repoKey, sessionShort, taskSlug)`（join 拼装）、`integrationWorktreePath(worktreeRoot, repoKey, branchSanitized, jobId)`、`repoIdFromRoot`（FNV-1a 8-hex，**直搬 workspace-service.ts L682-690**：反斜杠规范化 + 尾斜杠剥离 + `0x811c9dc5`/`0x01000193`）。
+- **验收**：纯函数表驱动全绿；`repoIdFromRoot` 与源行为逐例一致（同路径同 id、Windows 反斜杠规范化、空路径→`_` 兜底语义照源 sanitize）；一切路径产物 `path.isAbsolute`。
+- **依赖**：T02（无代码依赖，仅需 GitPort 已定型避免返工）。
+
+### T04 StateStore（JSON 原子写持久化）
+- **目标**：`lib/state-store.js` —— DESIGN §7.1。
+- **范围/文件**：`lib/state-store.js`、`test/state-store.test.js`：`createStateStore({ path })` → `{ load(), persist(), get worktrees/jobs/repos, upsertWorktree, upsertJob, pruneTerminalJobs(keep=200), findActiveJob(repoKey, branch), findQueuedJobs(repoKey, branch), nextOrderIndex(repoKey, branch) }`。写纪律：深拷贝→stringify(,2)→tmp（`wx` + 0600 + best-effort chmod）→rename；`__proto__`/`constructor`/`prototype` 键防护；启动载入时终态 job 修剪。
+- **验收**：写后重载 round-trip 一致；0600 断言；proto 键注入被丢；修剪保留最近 N 条终态；并发 upsert（async 交错）无丢失（内存索引即真相）。
+- **依赖**：T02。
+
+### T05 repo-gate（canonical 门禁）
+- **目标**：`lib/repo-gate.js` —— DESIGN §5.2.0。
+- **范围/文件**：`lib/repo-gate.js`、`test/repo-gate.test.js`：`resolveRepoRoot({ repoArg, sessionCwd, workspacePaths, allowedRoots, git })`：缺省→sessionCwd→仍缺 throw `repo_unresolved`；`realpath` 失败 throw `repo_unknown`；非 git throw `not_a_git_repo`；门禁按序（session-cwd 子树 → workspace 列表 → allowedRoots）任一 `isPathInside`（规范化 + Windows 大小写不敏感，**照搬 aionui-panel gate.ts L30-45**）通过，全拒 throw `repo_not_registered`（报 canonical + 指引）。无 any-root 开关。
+- **验收**：符号链接 repo（realpath 后命中 workspace）通过；`..` 逃逸、未注册绝对路径、allowedRoots 外路径均拒；sessionCwd 缺席 + 无 workspaceRegistry 时的降级路径正确。
+- **依赖**：T02。
+
+---
+
+## P2 工作区服务
+
+### T06 WorktreeService（workspace-service 收窄版）
+- **目标**：worktree 模式 CRUD —— DESIGN §5.2.1/§5.3/§5.4/§5.5/§5.8 引擎侧。
+- **范围/文件**：`lib/worktree-service.js`、`test/worktree-service.test.js`。
+  - `create({ task, repoRoot, baseRef, integrationBranch, note, sessionId, cfg })`：`validateBranch(sanitizeBranch)` → 重名 `branch_exists` → `maxWorktrees` 超限 `max_worktrees_reached` → `resolveRef(baseRef ?? cfg.defaultBaseRef)`（**禁 mutable-HEAD 回退：base 必须落成具体 oid**，语义照搬 workspace-service.ts L268-284）→ 父目录预建 + `createWorktree` → 记录（active）。
+  - `list({ repoRoot? })`：对照 `gitPort.listWorktrees` 标 `orphaned/vanished`；`status(idOrPath)`：head/dirty/changes(porcelain 映射)/ahead。
+  - `cleanup({ idOrPath, force, acknowledge, keepBranch })`：**保护判定** —— 记录非 merged 且 `!isAncestor(repoRoot, sourceHead, integrationHead)` 且 `!(force && acknowledge)` → throw `cleanup_protected`（消息含 sourceHead/integrationHead/两参数用法）；通过 → `removeWorktree`（幂等）+ `branch -D`（keepBranch false 时；分支删除用 `["branch","-D","--",branch]`）；vanished 记录只清状态。
+- **验收**：真 git fixture 全链（create→写文件→cleanup 保护拒绝→force+acknowledge 放行）；`branch_exists` 幂等语义； vanished 清记录不碰 git 成功。
+- **依赖**：T02 T03 T04 T05。
+
+### T07 查询工具三件（list/status/create）
+- **目标**：`lib/tools/worktree-create.js` / `worktree-list.js` / `worktree-status.js` —— DESIGN §5.3-5.5 的 schema 与返回形状。
+- **范围/文件**：三工具模块 + `test/tools.test.js`（fake ctx：`tools.register` 收集器 + 真 git fixture）：参数 schema 逐字对齐 DESIGN §5.3-5.5；返回对象**条件展开构造**（无 undefined 值键 —— json-safe E3 纪律）；create 的 `delegate_hint` 含 subagent cwd 组合提示文案；错误码族齐备（`repo_*` / `invalid_*` / `branch_exists` / `max_worktrees_reached`）。
+- **验收**：fake ctx 注册断言（name/description 含组合示例）；create 返回 path 即 GitPort 产物（fixture 验证真 worktree 存在）；status 的 changes 映射（added/modified/renamed…）用 porcelain 构造样例断言。
+- **依赖**：T06。
+
+---
+
+## P3 集成队列
+
+### T08 MergeQueue 引擎（骨架 + collect）
+- **目标**：`lib/merge-queue.js` —— DESIGN §6。
+- **范围/文件**：`lib/merge-queue.js`、`test/merge-queue.test.js`。
+  - `collect(worktree)`：status →（autoCollect 且脏）`commitAll` → `resolveHead`；净树且 `mergeBase(head, base) === head` → `{ state:'no_changes' }`（**change-collector.ts L162-222 语义直搬**，no_changes 在 DSH 降级为正常结局）。
+  - `enqueue(params)`（origin/correlationId 字段 day-one）；`drain(repoKey, branch)`：promise 链（`Map<key, Promise>` 尾接续，finally 自清）→ `applyUntilBlockedOrEmpty`。
+  - `applyOne` 十步（DESIGN §6.3 对照表逐步）：**步骤 5 先写 job.integrationWorktree/integrationHeadBefore 再跑 git**（崩溃证据写序）；步骤 7 `mergeNoFf`；步骤 8 冲突分类（非零退出 → listConflicts → 非空或 /conflict/i → conflicted 记 conflictFiles **保留 worktree**；否则 `abortMerge` best-effort → failed）；步骤 10 finally 非 conflicted removeWorktree（best-effort）。
+  - 命令 `cancel/retry/resolve`（**merge-queue.ts L266-400 逐条直搬语义**：幂等 + invalid_state 矩阵 + 分支释放触发 drain）；resolve/retry 不删 retained worktree（源 L309-311 注释语义，记 `abandonedIntegrationWorktrees`）。
+  - `MergeError` 形状映射 DESIGN §5.6（active_job_exists 是返回态非异常）。
+- **验收**：迁移用例全绿 —— enqueue 单调序（merge-queue.test L358-399）、clean merge（merge --no-ff 版：集成 HEAD 是 merge commit 且源提交全在）、conflict（conflictFiles + worktree 保留断言）、one-active + 冲突后阻塞（drain 版）、cancel/retry/resolve 幂等与 invalid_state 矩阵（commands.test L166-382 语义）、collect 脏树/净树两态；新增：两分支并行 drain 不互阻、同分支严格串行、多提交源分支无损集成。
+- **依赖**：T06（用其记录形状与 GitPort）。
+
+### T09 写工具三件（merge/queue/cleanup）
+- **目标**：`lib/tools/worktree-merge.js` / `worktree-queue.js` / `worktree-cleanup.js` —— DESIGN §5.6-5.8。
+- **范围/文件**：三工具模块 + tools.test 扩展：merge 的 `isConcurrencySafe: () => false`；返回 oneOf 五态（succeeded/conflicted(含 resolution_hint)/queued(queued_ahead)/no_changes/failed）形状逐字对齐；queue 的四 action（list 含 branch_holders）；cleanup 双布尔保护 + keep_branch。
+- **验收**：真 git fixture 编排序列（DESIGN §5.3 组合示例 9 步全走通）；conflicted 返回的 integration_worktree 在 fixture 上真实存在且含冲突标记；`active_job_exists` 映射为 failed 返回态（非 throw）断言；cleanup 单 force 拒绝 / 双布尔放行。
+- **依赖**：T08。
+
+---
+
+## P4 总装
+
+### T10 apply() 总装
+- **目标**：`lib/index.js` + `lib/config.js` —— DESIGN §8.1/§8.2。
+- **范围/文件**：`lib/config.js`（zod strict §8.1 全表 + 未知键 fail loud）；`lib/index.js`：`export const inject = ['tools']`（workspaceRegistry 可选探测不进 inject）→ validateConfig → `assertSingleDshToolsInstance`（Symbol 自检，照搬 subagents lib/index.js L79-98）→ StateStore 载入 → **reconcile（先于工具注册**，DESIGN §7.3：applying→failed、vanished 标记、孤儿 integration 清理 best-effort、conflicted 原样保留、repo 不可达全标 orphaned）→ 按 register 开关注册六工具 → 返回 undefined。`lib/repo-gate.js` 的 workspacePaths 来源：`ctx.workspaceRegistry?.list()?.map(w => w.path)`（缺席→空数组降级）。
+- **验收**：`test/index.test.js`：装配后 fake ctx 有 6 工具；reconcile 对预置 state.json（含 applying job + 孤儿 worktree）的对账断言；config strict 拒未知键；apply 返回值严格 undefined。
+- **依赖**：T07 T09。
+
+### T11 bundle patch + README
+- **目标**：`cordis.patch.yml` 单 insert 行（DESIGN §8.3）+ 双语 README。
+- **范围/文件**：`cordis.patch.yml`（`- insert:` → `- id: worktrees` + `name: dsh-worktrees`，config 注释示例）；`README.md`/`README.zh.md`（中英同步：定位、安装（`dsh plugin --profile web add` + `npm run setup:peer`）、与 dsh-plugin-subagents 组合的编排示例（DESIGN §5.3 九步）、配置表、多 dsh 实例并发风险说明（O5）、非目标清单）；`CHANGELOG.md` 0.1.0；`AGENTS.md`（红线继承 DESIGN §12 十条）；`SECURITY.md`。
+- **验收**：YAML 可解析、行 id/name 形态与 dsh-ssh 先例一致；README 两语言段落对齐；组合示例与工具真实返回字段一致。
+- **依赖**：T10。
+
+### T12 lint + CI
+- **目标**：纪律机械化。
+- **范围/文件**：`scripts/lint.js`（`node --check` 全模块 + **git 出口纪律：`lib/` 内 `spawn(` 仅允许出现在 `git-port.js`**，正/反例内嵌测试）；`.github/workflows/ci.yml`（macOS/Ubuntu/Windows × Node 18/20/22，`npm ci && npm run lint && npm test`）；`npm pack --dry-run` 核对 files（lib/ cordis.patch.yml docs? README* CHANGELOG LICENSE）。
+- **验收**：CI 三平台绿（fixture 全本地 git，裸 runner 可过）；lint 对越界 spawn 样例报错；dry-run 内容物只含预期。
+- **依赖**：T10。
+
+---
+
+## 任务依赖速查
+
+| 任务 | 依赖 |
+|---|---|
+| T01 | — |
+| T02 | T01 |
+| T03 T04 T05 | T02 |
+| T06 | T02 T03 T04 T05 |
+| T07 | T06 |
+| T08 | T06 |
+| T09 | T08 |
+| T10 | T07 T09 |
+| T11 | T10 |
+| T12 | T10 |
+
+## 建议派发批次
+
+1. **批 1**：T01 → T02（GitPort 是一切地基，先行单独派）。
+2. **批 2**：T03 / T04 / T05 并行（纯逻辑互不依赖）。
+3. **批 3**：T06 →（T07 / T08 并行）。
+4. **批 4**：T09 → T10。
+5. **批 5**：T11 / T12 并行收尾。
+
+## 工程量预算（对照 DESIGN §13）
+
+| 任务 | 预估 |
+|---|---|
+| T01 | 0.25 天 |
+| T02 | 1 天（直搬 585 行 + 迁测 593 行 + 5 新方法） |
+| T03+T04+T05 | 各 0.5 天（可并行） |
+| T06 | 1 天 |
+| T07 | 0.5 天 |
+| T08 | 1.5 天（核心：十步 + 命令 + 冲突保留断言） |
+| T09 | 1 天（编排序列端到端） |
+| T10 | 0.75 天（reconcile 是隐藏工作量） |
+| T11+T12 | 0.5 天 |
+| **合计** | **~7.5 人日**（单人）；并行派发（批 2/3 双代理）可压缩至 ~5 个日历日 |

package/lib/config.js

@@ -0,0 +1,126 @@
+/**
+ * Configuration validation (T10, DESIGN §8.1).
+ *
+ * zod strict schema, field-for-field the §8.1 table. Invalid config —
+ * including unknown/misspelled keys — fails LOUDLY at apply time with a
+ * precise message instead of surfacing as a confusing runtime error later
+ * (style follows dsh-plugin-subagents lib/config.js).
+ *
+ * validateConfig(rawConfig) returns the RESOLVED final config: every
+ * optional key carries its §8.1 default, `register` is normalised into the
+ * full six-boolean form, and the two path defaults are materialised from
+ * os.homedir():
+ *   - worktreeRoot → ~/.dsh/worktrees/
+ *   - statePath    → ~/.dsh/dsh-worktrees/state.json
+ *
+ * Engines receive this resolved object verbatim (createWorktreeService /
+ * createMergeQueue apply only defensive numeric guards on top).
+ */
+
+import { z } from 'zod'
+import os from 'node:os'
+import path from 'node:path'
+
+/** Default worktree root: `~/.dsh/worktrees/` (DESIGN §8.1). */
+export function defaultWorktreeRoot() {
+  return path.join(os.homedir(), '.dsh', 'worktrees')
+}
+
+/** Default state file: `~/.dsh/dsh-worktrees/state.json` (DESIGN §7.1/§8.1). */
+export function defaultStatePath() {
+  return path.join(os.homedir(), '.dsh', 'dsh-worktrees', 'state.json')
+}
+
+/**
+ * Tool-family switches (§8.1 `register`) — all optional booleans, strict
+ * (an unknown switch name is a config typo and fails loud).
+ */
+export const registerSchema = z.object({
+  create: z.boolean().optional(),
+  list: z.boolean().optional(),
+  status: z.boolean().optional(),
+  merge: z.boolean().optional(),
+  queue: z.boolean().optional(),
+  cleanup: z.boolean().optional(),
+}).strict()
+
+/**
+ * The full §8.1 plugin config table. `.strict()` on every object level so
+ * unknown keys (typos like `worktreeRoots` or `maxWorktree`) reject at
+ * apply time instead of being silently ignored.
+ */
+export const pluginConfigSchema = z.object({
+  register: registerSchema.optional(),
+  worktreeRoot: z.string().min(1).optional(),
+  statePath: z.string().min(1).optional(),
+  maxWorktrees: z.number().int().positive().optional(),
+  defaultBaseRef: z.string().min(1).optional(),
+  gitTimeoutMs: z.number().int().positive().optional(),
+  mergeTimeoutMs: z.number().int().positive().optional(),
+  allowedRoots: z.array(z.string().min(1)).optional(),
+  requireWorkspaceRegistration: z.boolean().optional(),
+  autoCollect: z.boolean().optional(),
+  retainJobHistory: z.number().int().positive().optional(),
+}).strict()
+
+/** register defaults: the whole tool family is on unless switched off. */
+export const REGISTER_DEFAULTS = Object.freeze({
+  create: true,
+  list: true,
+  status: true,
+  merge: true,
+  queue: true,
+  cleanup: true,
+})
+
+/** Scalar defaults (§8.1 comment column). */
+export const SCALAR_DEFAULTS = Object.freeze({
+  maxWorktrees: 16,
+  defaultBaseRef: 'HEAD',
+  gitTimeoutMs: 15_000,
+  mergeTimeoutMs: 120_000,
+  requireWorkspaceRegistration: true,
+  autoCollect: true,
+  retainJobHistory: 200,
+})
+
+/**
+ * Validate + resolve the raw plugin config (DESIGN §8.1).
+ *
+ * @param {object} [config] raw host config
+ * @returns {{
+ *   register: {create: boolean, list: boolean, status: boolean, merge: boolean, queue: boolean, cleanup: boolean},
+ *   worktreeRoot: string, statePath: string,
+ *   maxWorktrees: number, defaultBaseRef: string,
+ *   gitTimeoutMs: number, mergeTimeoutMs: number,
+ *   allowedRoots: string[], requireWorkspaceRegistration: boolean,
+ *   autoCollect: boolean, retainJobHistory: number,
+ * }} the final config with every default applied
+ * @throws {Error} `dsh-worktrees: invalid config — <issues>` on any unknown
+ *   key or out-of-contract value (zod strict behaviour, wrapped with a
+ *   clear message)
+ */
+export function validateConfig(config = {}) {
+  const result = pluginConfigSchema.safeParse(config)
+  if (!result.success) {
+    const issues = result.error.issues.map(
+      (issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`,
+    )
+    throw new Error(`dsh-worktrees: invalid config — ${issues.join('; ')}`)
+  }
+  const raw = result.data
+  return {
+    register: { ...REGISTER_DEFAULTS, ...(raw.register ?? {}) },
+    worktreeRoot: raw.worktreeRoot ?? defaultWorktreeRoot(),
+    statePath: raw.statePath ?? defaultStatePath(),
+    maxWorktrees: raw.maxWorktrees ?? SCALAR_DEFAULTS.maxWorktrees,
+    defaultBaseRef: raw.defaultBaseRef ?? SCALAR_DEFAULTS.defaultBaseRef,
+    gitTimeoutMs: raw.gitTimeoutMs ?? SCALAR_DEFAULTS.gitTimeoutMs,
+    mergeTimeoutMs: raw.mergeTimeoutMs ?? SCALAR_DEFAULTS.mergeTimeoutMs,
+    allowedRoots: raw.allowedRoots ?? [],
+    requireWorkspaceRegistration:
+      raw.requireWorkspaceRegistration ?? SCALAR_DEFAULTS.requireWorkspaceRegistration,
+    autoCollect: raw.autoCollect ?? SCALAR_DEFAULTS.autoCollect,
+    retainJobHistory: raw.retainJobHistory ?? SCALAR_DEFAULTS.retainJobHistory,
+  }
+}

package/lib/engine-face.js

@@ -0,0 +1,328 @@
+/**
+ * engine-face — the `worktreesEngine` Cordis service face (DESIGN §10 seam,
+ * audit P0: the four-layer contract drift with dsh-dag-orchestrator).
+ *
+ * WHY THIS MODULE EXISTS. dsh-dag-orchestrator consumes this plugin through
+ * the OPPORTUNISTIC service probe `ctx.get('worktreesEngine')`
+ * (its lib/worktrees-seam.js admits exactly `{getMergeQueue, getWorktreeService}`
+ * as functions). The plugin used to satisfy only the *shape* of that probe
+ * while drifting on four behavioural layers the DAG's frozen acceptance
+ * tests pin (its test/merge-executor.test.js + test/worktree-task.test.js
+ * fake engines). This module adapts the LIVE engine singletons to that
+ * consumer contract WITHOUT touching the tool-layer contracts:
+ *
+ *   a) `service.create` — the DAG calls `create({task, repoRoot, baseRef,
+ *      origin:'dag', correlationId, …})` with NO repoKey/sessionId. The
+ *      WorktreeService itself now derives repoKey (repoIdFromRoot) and
+ *      persists origin/correlationId on the record; the facade only has to
+ *      supply the sessionId the branch name derives from (a stable
+ *      engine-level id — DAG-created worktrees must not depend on a
+ *      calling agent session existing).
+ *
+ *   b) `service.findActiveByTask(repoRoot, task)` — implemented directly on
+ *      the WorktreeService (the reuse probe's lookup); the facade passes
+ *      it through untouched.
+ *
+ *   c) `queue.enqueue` — the DAG passes the FOUR-key form
+ *      `{worktreeId, integrationBranch, origin, correlationId}`; git facts
+ *      (repoKey/repoRoot/sourceBranch/sourceHead) are resolved
+ *      SERVER-SIDE from the worktree record (the DAG never learns git:
+ *      sourceHead = the worktree's CURRENT head, sourceBranch = the
+ *      record's branch). The integration branch is vetted with
+ *      check-ref-format (audit P1-B) before anything is persisted. The
+ *      DAG's IDEMPOTENCE contract is implemented here too: while a job for
+ *      the same (worktreeId, integrationBranch) is still active
+ *      (queued/applying/conflicted), enqueue RETURNS that job instead of
+ *      stacking a duplicate — a DAG retry re-polls, it does not re-stack.
+ *      The queue's own seven-key enqueue stays synchronous and unchanged.
+ *
+ *   d) `queue.drain` — the DAG requires the five-state DrainOutcome
+ *      `{succeeded|conflicted|failed|no_changes|queued(queued_ahead)}`
+ *      (its lib/executors/merge.js module header); the internal drain
+ *      returns the tool-layer `{drained}|{blockedBy}` shape, which must
+ *      NOT change (worktree_merge maps it). The facade wraps the SAME
+ *      serial chain — one drain call, two projections. A dirty-source
+      guard (audit P3) sits inside the `succeeded` projection: before
+      reporting success, the source worktree(s) whose commits were
+      integrated are re-checked for uncommitted changes; a dirty worktree
+      maps `succeeded` → `failed` / `dirty_not_collected` (the seam twin
+      of the tool layer's collect gate), reusing the GitPort's `status`
+      porcelain as the shared dirty judgment.
+ *
+ * Single-writer invariant (red line 10): the facade holds NO state of its
+ * own — every method delegates to the SAME store/git-backed service and
+ * queue singletons the tools use. This module is glue only.
+ */
+
+import { assertValidIntegrationBranch, MergeError } from './merge-queue.js'
+
+/** Merge-job states that hold the per-branch queue slot (state-store set). */
+const ACTIVE_JOB_STATES = new Set(['queued', 'applying', 'conflicted'])
+
+/**
+ * The DAG-facing merge queue: the LIVE queue's serial chain with the
+ * four-key enqueue completion and the DrainOutcome five-state projection
+ * layered on top.
+ *
+ * @param {object} queue createMergeQueue() product (the tool-layer face)
+ * @param {object} store the SAME StateStore the queue was built with
+ * @param {object} git the SAME GitPort the queue was built with (head
+ *   resolution + check-ref-format vetting for the four-key form)
+ * @returns {object} the engine-seam queue face (enqueue/drain DAG-adapted;
+ *   every other member passes through by identity)
+ */
+export function createEngineQueueFace(queue, store, git) {
+  /**
+   * DAG enqueue: complete the seven-key form from the worktree record,
+   * vet the integration branch (P1-B), then hand the completed job to the
+   * live queue's own enqueue. Idempotence-while-active is checked FIRST.
+   */
+  /**
+   * The dirty-source guard for the DRAIN projection (audit P3 — the seam
+   * twin of the tool layer's `dirty_not_collected` collect gate): a source
+   * worktree holding uncommitted changes means those changes were NOT in the
+   * HEAD the drain just integrated — reporting `succeeded` would be the same
+   * "success illusion" the tool layer's collect `dirty_not_collected` stops
+   * (lib/merge-queue.js collect, mapped by lib/tools/worktree-merge.js).
+   *
+   * The DAG four-key path deliberately does NOT auto-collect (the DAG's
+   * agent executor owns the worktree's commits, so the seam behaves as the
+   * tool layer's autoCollect=false branch): a dirty source is a loud FAIL,
+   * the remediation is to commit the work first or drive it through the
+   * tool layer's autoCollect.
+   *
+   * The dirty judgment REUSES the tool layer's own primitive — the GitPort's
+   * `git.status()` porcelain (porcelain non-empty == dirty) — rather than
+   * re-implementing a parser here (drift guard). A missing worktree record
+   * (externally-seeded job) or a status flake fails OPEN toward clean: the
+   * merge itself is the integrated state's authority, and an unresolvable
+   * status must not fabricate a failure the tool layer would not.
+   *
+   * @param {object} job a terminal `succeeded` merge-job record.
+   * @returns {Promise<{worktreeId: string, error: string} | null>} the first
+   *   dirty source (error carries `dirty_not_collected`), or null when clean
+   *   / not determinable.
+   */
+  async function dirtySourceOf(job) {
+    if (!job || typeof job.worktreeId !== 'string' || job.worktreeId.length === 0) return null
+    const record = store.worktrees[job.worktreeId]
+    if (!record || typeof record.path !== 'string' || record.path.length === 0) return null
+    let entries
+    try {
+      entries = await git.status(record.path)
+    } catch {
+      return null // status flake / missing tree — fail open (see JSDoc)
+    }
+    if (!Array.isArray(entries) || entries.length === 0) return null
+    return {
+      worktreeId: job.worktreeId,
+      error:
+        'dirty_not_collected: the worktree ' + JSON.stringify(job.worktreeId) +
+        ' has uncommitted changes that were NOT part of the HEAD the drain integrated, ' +
+        'so the merge result silently excluded them; commit this work first ' +
+        '(or drive it through the tool layer\'s autoCollect), then re-run the merge',
+    }
+  }
+
+  async function enqueue(params = {}) {
+    const { worktreeId, integrationBranch } = params
+    if (typeof worktreeId !== 'string' || worktreeId.length === 0) {
+      throw new MergeError('invalid_params', 'engine enqueue requires a non-empty string worktreeId')
+    }
+    // Git facts are the provider's business (the DAG never learns git).
+    const record = store.worktrees[worktreeId]
+    if (record === undefined) {
+      throw new MergeError(
+        'worktree_not_found',
+        `engine enqueue: no worktree record for worktreeId ${JSON.stringify(worktreeId)}`,
+      )
+    }
+    // The effective branch key: an omitted integrationBranch falls back to
+    // the record's own (DESIGN §10 seam — the DAG may omit it). The
+    // idempotence scan below compares this SAME effective key whether or not
+    // the DAG supplied it, so omitting the field can never widen the match
+    // (a defensive branch-dimension check on an undefined value would skip
+    // the comparison entirely and let an active job for a DIFFERENT branch
+    // on the same worktree be returned).
+    const branch = integrationBranch ?? record.integrationBranch
+    await assertValidIntegrationBranch(git, record.repoRoot, branch)
+
+    // Idempotence-while-active: an active job for the same
+    // (worktreeId, integrationBranch) is RETURNED, not stacked. The branch
+    // dimension always participates (never a bare `integrationBranch !==
+    // undefined` guard — the effective key is `branch` above).
+    for (const job of Object.values(store.jobs)) {
+      if (job.worktreeId !== worktreeId) continue
+      if (job.integrationBranch !== branch) continue
+      if (!ACTIVE_JOB_STATES.has(job.state)) continue
+      return job
+    }
+
+    let sourceHead = record.headCommit
+    if (typeof sourceHead !== 'string' || sourceHead.length === 0) {
+      try {
+        sourceHead = (await git.resolveHead(record.path)).commit
+      } catch (error) {
+        throw new MergeError(
+          'invalid_params',
+          `engine enqueue: cannot resolve the current head of worktree ${worktreeId} ` +
+            `(${record.path}): ${error instanceof Error ? error.message : String(error)}`,
+        )
+      }
+    }
+    return queue.enqueue({
+      repoKey: record.repoKey,
+      repoRoot: record.repoRoot,
+      integrationBranch: branch,
+      worktreeId,
+      sourceBranch: record.branch,
+      sourceHead,
+      ...(params.message !== undefined && params.message !== null ? { message: params.message } : {}),
+      origin: params.origin === 'dag' ? 'dag' : 'tool',
+      ...(params.correlationId !== undefined && params.correlationId !== null
+        ? { correlationId: params.correlationId }
+        : {}),
+    })
+  }
+
+  /**
+   * DAG drain: the five-state DrainOutcome projection of the live drain.
+   *
+   * Mapping (internal drain outcome → DrainOutcome):
+   *  - blocked by a conflicted holder → `{conflicted, conflictFiles,
+   *    integrationWorktree?}` (the retained scene);
+   *  - blocked by an applying holder (another caller's in-flight apply) →
+   *    `{queued, queued_ahead}` — not terminal this round, re-poll later;
+   *  - drained → inspect the branch's terminal jobs: the most recent
+   *    succeeded → `{succeeded, integratedCommit}`; the most recent
+   *    failed → `{failed, error}`; NO terminal jobs at all →
+   *    `{no_changes}` (an empty integration is legal, DESIGN §11.1).
+   *
+   * `queued_ahead` counts the queued jobs on the branch — the DAG's
+   * snake_case contract key (m-5).
+   */
+  async function drain(repoKey, integrationBranch) {
+    const outcome = await queue.drain(repoKey, integrationBranch)
+
+    // Which jobs exist for this branch, and their settled states.
+    const branchJobs = Object.values(store.jobs).filter(
+      (job) => job.repoKey === repoKey && job.integrationBranch === integrationBranch,
+    )
+    const queued = branchJobs.filter((job) => job.state === 'queued')
+
+    if (outcome !== null && typeof outcome === 'object' && outcome.blockedBy !== undefined) {
+      const blocker = outcome.blockedBy
+      if (blocker.state === 'conflicted') {
+        return {
+          state: 'conflicted',
+          conflictFiles: Array.isArray(blocker.conflictFiles) ? [...blocker.conflictFiles] : [],
+          ...(typeof blocker.integrationWorktree === 'string'
+            && blocker.integrationWorktree.length > 0
+            ? { integrationWorktree: blocker.integrationWorktree }
+            : {}),
+        }
+      }
+      // applying (or an unexpected active state): not terminal this round.
+      return { state: 'queued', queued_ahead: queued.length }
+    }
+
+    // Drained (or an empty queue from the start): project the last job's
+    // terminal state; no jobs at all → no_changes.
+    const terminal = branchJobs
+      .filter((job) => job.state === 'succeeded' || job.state === 'failed')
+      .sort((a, b) => (Number(b.updatedAt) || 0) - (Number(a.updatedAt) || 0))
+    if (terminal.length === 0) {
+      return { state: 'no_changes' }
+    }
+    const last = terminal[0]
+    if (last.state === 'failed') {
+      return { state: 'failed', error: String(last.error ?? 'merge failed') }
+    }
+    // Dirty-source guard (audit P3): before reporting `succeeded`, confirm
+    // the source worktree(s) whose commits were just integrated are CLEAN at
+    // drain time. If any terminal succeeded source still holds uncommitted
+    // changes, those changes were excluded from the merged HEAD — map to the
+    // terminal `failed` / `dirty_not_collected` (the DAG already maps a
+    // `failed` DrainOutcome to a transient `dag.merge_failed` retry).
+    for (const done of terminal) {
+      if (done.state !== 'succeeded') continue
+      const dirty = await dirtySourceOf(done)
+      if (dirty !== null) {
+        return { state: 'failed', error: dirty.error }
+      }
+    }
+    return {
+      state: 'succeeded',
+      ...(typeof last.integratedCommit === 'string' && last.integratedCommit.length > 0
+        ? { integratedCommit: last.integratedCommit }
+        : {}),
+    }
+  }
+
+  // Everything else passes through BY IDENTITY — the queue's own methods,
+  // unchanged (collect/cancel/retry/resolve/listJobs/branchHolders/…).
+  return new Proxy(queue, {
+    get(target, prop, receiver) {
+      if (prop === 'enqueue') return enqueue
+      if (prop === 'drain') return drain
+      const value = Reflect.get(target, prop, target)
+      return typeof value === 'function' ? value.bind(target) : value
+    },
+  })
+}
+
+/**
+ * The DAG-facing worktree service: the LIVE service with create() adapted
+ * to the DAG call shape.
+ *
+ * @param {object} service createWorktreeService() product
+ * @param {object} opts
+ * @param {string} opts.engineSessionId stable session id for DAG-created
+ *   worktrees (branch names derive from it; defaults to 'dsh-dag-engine')
+ * @returns {object} the engine-seam service face
+ */
+export function createEngineServiceFace(service, { engineSessionId = 'dsh-dag-engine' } = {}) {
+  /**
+   * DAG create: fills sessionId (the DAG does not have one) and forwards.
+   * repoKey is derived inside the service; origin/correlationId pass
+   * through and land on the persisted record (the reuse-ownership gate's
+   * evidence).
+   */
+  async function create(params = {}) {
+    return service.create({
+      ...params,
+      sessionId:
+        typeof params.sessionId === 'string' && params.sessionId.length > 0
+          ? params.sessionId
+          : engineSessionId,
+    })
+  }
+
+  return new Proxy(service, {
+    get(target, prop, receiver) {
+      if (prop === 'create') return create
+      const value = Reflect.get(target, prop, target)
+      return typeof value === 'function' ? value.bind(target) : value
+    },
+  })
+}
+
+/**
+ * Assemble the `worktreesEngine` service value provided on the Cordis ctx.
+ *
+ * @param {{
+ *   service: object, queue: object, store: object, git: object,
+ *   engineSessionId?: string,
+ * }} deps the LIVE singletons (the SAME instances the tools use — red
+ *   line 10: one writer, one store, one serial chain).
+ * @returns {{getMergeQueue: () => object, getWorktreeService: () => object, available: true}}
+ */
+export function createEngineFace({ service, queue, store, git, engineSessionId } = {}) {
+  const queueFace = createEngineQueueFace(queue, store, git)
+  const serviceFace = createEngineServiceFace(service, { engineSessionId })
+  return {
+    getMergeQueue: () => queueFace,
+    getWorktreeService: () => serviceFace,
+    available: true,
+  }
+}