dsh-plugin-worktrees 0.1.0

package/AGENTS.md

@@ -0,0 +1,120 @@
+# AGENTS.md
+
+Guidance for AI agents (DeepSeek Harness agents, Claude Code, Codex, …)
+working in this repository.
+
+## What this is
+
+`dsh-worktrees` — a DeepSeek Harness (Cordis) plugin providing git worktree
+parallel write isolation plus serial merge integration: six new-name tools
+(`worktree_create / list / status / merge / queue / cleanup`), a serial
+merge queue into a session integration branch (`merge --no-ff`), conflict
+scenes retained for out-of-band resolution, crash reconciliation at apply
+time, and a double-confirmation cleanup. The core engine is ported from
+task-weaver's `packages/workspaces/`; the design record is
+[docs/DESIGN.md](docs/DESIGN.md) and the task breakdown is
+[docs/TASKS.md](docs/TASKS.md).
+
+## Commands
+
+```bash
+npm install        # install dependencies
+npm run setup:peer # symlink the RUNNING harness's @deepseek-ai/dsh-tools
+npm test           # node:test suite (295 tests; real local git fixtures, no network)
+npm run lint       # node --check every module + the git-ingress audit
+```
+
+Never add a test that requires a network, a remote, or credentials — the
+suite must stay green on a bare runner. When migrating code from
+task-weaver, do not weaken migrated assertions; new cases add coverage,
+they don't change old semantics.
+
+## Repo layout
+
+```
+cordis.patch.yml      # bundle patch: ONE insert row (id: worktrees) — no disables
+lib/
+  index.js            # apply(): config, peer self-check, state load, reconcile, tool registration
+  config.js           # zod strict config (§8.1 table; unknown keys fail loudly)
+  git-port.js         # the ONLY git ingress: runGit + NodeGitPort + porcelain parsers
+  state-store.js      # one JSON file: atomic 0600 tmp+rename writes, __proto__ guard
+  repo-gate.js        # realpath + session-cwd/workspace/allowedRoots admission (fail closed)
+  naming.js           # sanitizeBranch / branchName / worktreePath / repoIdFromRoot (FNV-1a)
+  worktree-service.js # create/list/status/cleanup/findActiveByTask (task-weaver workspace-service, worktree mode only)
+  merge-queue.js      # enqueue/drain/applyOne + collect + cancel/retry/resolve
+  engine-face.js      # the worktreesEngine service face (§10.1 DAG seam: four-key enqueue, five-state drain, create/findActiveByTask)
+  tools/              # one module per model-facing tool (6 modules)
+scripts/              # lint.js (syntax + git-discipline audit), link-harness-dsh-tools.sh
+test/                 # node:test suite (real local git fixtures)
+docs/DESIGN.md        # the architecture record — read before changing semantics
+docs/TASKS.md         # task breakdown and acceptance criteria
+```
+
+## Safety red lines (non-negotiable)
+
+All ten are binding (DESIGN §12); they were decided before implementation
+and every one of them is mechanically or structurally enforced:
+
+1. **The GitPort is the only git ingress.** Every git call goes through
+   `lib/git-port.js` (`spawn("git", argvArray, {shell:false})`) — argv is
+   never a shell string. `scripts/lint.js` enforces this statically: no
+   module under `lib/` other than `git-port.js` may contain a
+   process-spawning call (`spawn(` / `spawnSync(` / `exec(` / `execSync(` /
+   `execFile(` / `execFileSync(`), real forms only (a `name(` after the
+   method name; `child_process` imports and string mentions do not trip).
+2. **Ref/branch-name injection defence.** Caller-controllable refs are
+   always resolved with `rev-parse --verify --end-of-options`; branch names
+   (task slugs AND explicitly supplied integration branches — at create,
+   at the merge override, at the engine-seam enqueue, and re-vetted at
+   apply time) are pre-vetted with `check-ref-format --branch`;
+   merge/delete positional refs sit AFTER the `--` end-of-options
+   terminator.
+3. **Path discipline.** `node:path.join`/`resolve` + `realpath`
+   normalisation everywhere — never string concatenation or `URL.pathname`.
+   Worktree physical paths land only under `worktreeRoot` (constructive
+   guarantee; the caller cannot inject a leaf directory).
+4. **The repo gate fails closed.** A repo root must realpath inside the
+   union of registered workspaces, the session-cwd subtree, and explicit
+   `allowedRoots`. There is NO any-root switch; the unknown is always
+   `repo_not_registered`.
+5. **Cleanup never deletes unmerged work.** While the source branch head is
+   not an ancestor of the integration branch head — OR the integration
+   branch does not resolve (never bootstrapped) while the worktree holds
+   commits past its recorded baseCommit — removal requires
+   `force && acknowledge` — two INDEPENDENT booleans simultaneously and
+   explicitly true. No single parameter or default ever releases it.
+6. **Merge never auto-pushes.** The GitPort structurally has no
+   push/fetch/clone method; the README and the tool descriptions state that
+   integration results stay on the local integration branch for human
+   review and push.
+7. **The conflict scene is untouchable.** A conflicted job's integration
+   worktree and source branch are retained; reconciliation and `retry`
+   never delete them. Only an explicit cleanup (past the protection check)
+   or a post-`resolve` explicit action may clear the scene.
+8. **Tests use zero network and zero remotes.** Fixtures are local
+   `git init` only; no case may push/fetch/clone (CI must stay green on a
+   bare runner).
+9. **Config is zod-strict.** Unknown keys fail loudly (family convention);
+   `engines >= 18` — no `Promise.withResolvers` (hand-written deferreds).
+10. **Single-writer invariant.** Writes to `state.json` happen only inside
+    the engine's serial chain or a tool's single-step critical section; the
+    plugin offers no second write entrance (the dag-orchestrator goes
+    through the `worktreesEngine` service face, which wraps the SAME
+    engine/tool singletons — DESIGN §10/§10.1).
+
+## Engineering discipline
+
+- `node:test` only — no real CLIs, no keys, no network (family red line).
+- A migration never weakens assertions; ports stay line-for-line equivalent
+  except where DESIGN explicitly requires a rename or an extension, and
+  original comment semantics are preserved.
+- README.md and README.zh.md are updated **together** — section-for-section
+  aligned whenever the config surface, tools, install flow, or the safety
+  boundaries change.
+- Every user-visible change gets a `CHANGELOG.md` entry.
+- Keep `lib/index.js` thin: assembly only; tools live in `lib/tools/`, one
+  module per tool; engines are constructor-injected (`{ git, store,
+  config }`) and never import host services.
+- `apply()` must return `undefined` (the loader treats a non-undefined
+  return as a disposable and fails the boot with `TypeError: Invalid
+  effect`).

package/CHANGELOG.md

@@ -0,0 +1,266 @@
+# Changelog
+
+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.0] - 2026-08-18
+
+First release. `dsh-worktrees` gives the DeepSeek Harness **git worktree
+parallel write isolation + serial merge integration**: one isolated worktree
+per parallel task (dedicated branch `dsh-wt/<session-short>/<task>`), a
+serial merge queue into a session integration branch, and conflict scenes
+that are retained for out-of-band resolution. The core engine is ported from
+task-weaver's `packages/workspaces/` (migration map: DESIGN §9); the plugin
+pattern follows dsh-plugin-subagents.
+
+### Documentation (2026-08-18) — README rewrite
+
+- Both READMEs (`README.md` / `README.zh.md`) rewritten in plain language,
+  still section-for-section aligned. New shape: what the plugin gives you →
+  why (parallel write agents racing in one checkout) → install (npm name
+  plus local-checkout path) with an expected result → quick start showing
+  the create/delegate/merge/resolve loop → the six tools → the five merge
+  outcomes → conflicts in one paragraph → safety features in user terms →
+  trimmed configuration table → boundaries & troubleshooting → references
+  & credits. Internal vocabulary (DESIGN codes, semver prerelease arcana,
+  test counts) was dropped from the READMEs.
+
+### Changed (2026-08-18)
+
+- npm package renamed to `dsh-plugin-worktrees`: the unscoped name
+  `dsh-worktrees` was taken on npm by an unrelated third-party package
+  (different author, different functionality). The dsh bundle id in
+  `cordis.patch.yml` stays `worktrees`; only the npm distribution name
+  changed. First npm release: 0.1.0.
+
+### CI (2026-08-18)
+
+- windows-latest leg DEFERRED: all Windows legs failed 42
+  git-path-sensitive assertions (worktree-listing path shapes, engine-face
+  record visibility) that pass on macOS/ubuntu. Removed from the matrix
+  until Windows path semantics are implemented and validated;
+  `timeout-minutes: 15` added as a runaway guard.
+- Added gitleaks secret scanning: `.github/workflows/gitleaks.yml` (full
+  history scan on every push/PR) and `.pre-commit-config.yaml` for local
+  commits; matches the gateway-provider repo's setup plus a `.gitleaks.toml`
+  allowlist for the `dag/<case>/integration` test-fixture branch names the
+  generic-api-key entropy heuristic flags.
+### Added
+
+- **Six-tool family** (all new global-layer names — no official tool take
+  over, no preset adaptation, zero host patches):
+  - `worktree_create` — isolated worktree per parallel task; base ref always
+    resolved to a concrete commit oid; returns the path plus a delegation
+    hint pointing the subagent tool's `cwd` parameter at it.
+  - `worktree_list` — managed worktrees with the `orphaned` flag and a
+    merge-queue summary; `include_integration` also lists conflict-retained
+    integration worktrees.
+  - `worktree_status` — live git status (HEAD, dirty, per-file changes,
+    `ahead_of_base`) plus the worktree's merge-job projection.
+  - `worktree_merge` — auto-collect uncommitted work, enqueue, and serially
+    drain the branch queue; five-state return (`succeeded` / `conflicted` /
+    `queued` / `no_changes` / `failed`), with a held branch surfaced as the
+    `active_job_exists` return state (a business state, never a throw).
+  - `worktree_queue` — queue inspection (`list` + `branch_holders`) and the
+    `cancel` / `retry` / `resolve` commands (idempotent on terminal states;
+    invalid transitions fail loudly with `invalid_job_state`).
+  - `worktree_cleanup` — remove a worktree and its branch; unmerged work is
+    protected behind the `force` AND `acknowledge` double confirmation.
+- **Serial merge queue** (`lib/merge-queue.js`, ported from task-weaver
+  `merge-queue.ts`): per-branch promise chains replace exclusive leases
+  (strict serialisation inside one process), `merge --no-ff` replaces
+  cherry-pick (multi-commit branches integrate losslessly), one-active
+  invariant per repo+integration branch, monotonic `orderIndex`, terminal
+  job history pruned to `retainJobHistory` (200).
+- **Conflict scene retention**: on a conflict the integration worktree is
+  kept with the markers in place (the job holds its branch until
+  out-of-band resolution); `retry` re-queues while leaving the old scene
+  for the operator; nothing but an explicit, protection-checked cleanup
+  deletes it.
+- **Crash reconciliation** at `apply()` time, before any tool registration:
+  vanished worktrees marked, applying jobs failed with provenance (a live
+  partial integration worktree retained and annotated for inspection),
+  conflicted jobs kept verbatim, orphan `.integration/` worktrees
+  best-effort removed — marking only, no destructive deletes.
+- **Repo gate, fail closed** (`lib/repo-gate.js`): realpath canonicalisation
+  then admission only inside the session-cwd subtree, a registered
+  workspace, or explicit `allowedRoots`; no any-root switch.
+- **GitPort as the only git ingress** (`lib/git-port.js`, ported from
+  task-weaver): argv-array `spawn("git", …, {shell:false})`, per-command
+  timeouts with SIGKILL, dual-stream 8 MiB caps, `--verify
+  --end-of-options` ref resolution, `check-ref-format --branch` validation,
+  `--` terminators on positional refs — and structurally **no push / fetch /
+  clone** (no auto-push by construction).
+- **State store** (`lib/state-store.js`): one JSON file, atomic tmp+rename
+  writes with owner-only `0600` mode and a `__proto__`-key guard.
+- **zod-strict config** (`lib/config.js`): unknown keys fail loudly at
+  apply time; every default resolved centrally.
+- **Peer discipline**: `npm run setup:peer` symlinks the running harness's
+  `@deepseek-ai/dsh-tools`; `apply()` self-checks the single-instance
+  invariant (module-level Symbol probe) and fails loudly with the re-link
+  hint.
+- **Bundle patch** (`cordis.patch.yml`): one insert row (`id: worktrees`,
+  `name: dsh-worktrees`) — new-name tools are naturally visible on the
+  global layer, nothing to disable.
+- **Lint** (`scripts/lint.js`): `node --check` every module plus a static
+  git-discipline audit — `lib/` may spawn only from `git-port.js`, with
+  self-tests pinning the audit.
+- **Test suite**: 295 tests, `node --test`, real local git fixtures only —
+  zero network, zero remotes, green on a bare runner.
+
+### Fixed (audit round 1)
+
+- **P1-B — integration-branch name injection.** An explicitly supplied
+  `integration_branch` (create-time and the `worktree_merge` override)
+  reached `git branch <name> <startPoint>` / `git merge` unvalidated; a
+  flag-shaped value (`-m`) renamed `main` away to a 40-char oid (reproduced
+  by the `p1b` probe). Every entry point now pre-vets the name with
+  `git check-ref-format --branch` and rejects loudly with
+  `invalid_integration_branch` (naming the value and the legal-branch-name
+  rules); the merge queue re-vets at apply time as defense in depth, and
+  the engine seam vets the DAG four-key enqueue too.
+- **P1-C — pre-first-merge bare cleanup deleted unmerged work.** The
+  cleanup protection gate was skipped entirely while the integration branch
+  did not resolve (never bootstrapped), so a worktree holding commits past
+  its base could be bare-cleaned — directory, branch, and commit
+  reachability gone (reproduced by the `p1c` probe). When the integration
+  branch does not resolve, the gate now compares the worktree head against
+  the recorded `baseCommit`: anything past base is unmerged by definition
+  and triggers the same `cleanup_protected` double confirmation
+  (`force` AND `acknowledge`). A worktree with no commits past base stays
+  bare-cleanable. `worktree_cleanup`'s description documents both arms.
+- **P2 — `autoCollect: false` + a dirty tree reported a misleading
+  succeeded.** `collect` returned `ok` with the old head, the merge then
+  integrated that old head, and the uncommitted files were never
+  integrated. The outcome is now the explicit `dirty_not_collected`
+  terminal: `worktree_merge` returns
+  `state:'failed', error:'dirty_not_collected: …'` with the remediation
+  hint (commit the work or enable `autoCollect`), and no job is created.
+- **P3 — the `worktreesEngine` seam's drain projected a misleading
+  `succeeded` for a dirty worktree** (the DAG gap twin of P2). The DAG
+  four-key `enqueue → drain` path resolved `sourceHead` to the worktree's
+  current head and integrated it, so a worktree holding uncommitted changes
+  (never in that head) was reported `succeeded` — the same "success
+  illusion" the tool layer's `dirty_not_collected` stops. The seam's drain
+  projection now re-checks the integrated source worktrees' clean state
+  (reusing the GitPort's `git.status` porcelain judgment) and maps a dirty
+  source `succeeded` → `failed` / `dirty_not_collected` with the remediation
+  hint (commit the work first, or drive it through the tool layer's
+  `autoCollect`). The DAG consumer already handles a `failed` DrainOutcome
+  (transient `dag.merge_failed` retry), so the five-state contract is
+  unchanged. A missing worktree record or a status flake fails open.
+
+### Changed
+
+- **`mergeTimeoutMs` is now effective.** The key was validated but
+  discarded (`void config.mergeTimeoutMs`). It now budgets the merge step
+  specifically: `mergeNoFf` accepts a per-call `timeoutMs` override, the
+  queue passes the configured budget down, and a killed merge lands on the
+  normal hard-failure path (scene cleaned, queue continues) — separate
+  from the general 15s `gitTimeoutMs` so big-repo merges survive.
+
+### Added (audit round 1)
+
+- **`worktreesEngine` service face** (`lib/engine-face.js`, DESIGN §10.1):
+  `apply()` now provides `ctx.provide('worktreesEngine', …)` over the SAME
+  service/queue/store singletons the tools use (red line 10 — single
+  writer), adapting the frozen dsh-dag-orchestrator consumer contract:
+  - `service.create({task, repoRoot, baseRef?, origin:'dag',
+    correlationId})` — repoKey derived provider-side (repoIdFromRoot),
+    `origin`/`correlationId` persisted on the worktree record (optional
+    fields, old state.json files stay valid);
+  - `service.findActiveByTask(repoRoot, task)` — the DAG re-dispatch reuse
+    probe (returns the active record with its correlationId, the
+    ownership-gate evidence);
+  - `queue.enqueue({worktreeId, integrationBranch, origin, correlationId})`
+    — the DAG four-key form; git facts (repoKey/repoRoot/sourceBranch/
+    sourceHead) resolved server-side from the worktree record, the
+    integration branch check-ref-format vetted (P1-B), and idempotent
+    while a job is active (a DAG retry re-polls, never re-stacks);
+  - `queue.drain(repoKey, integrationBranch)` — the five-state
+    DrainOutcome (`succeeded`/`conflicted`/`failed`/`no_changes`/`queued`
+    + `queued_ahead`) projected on top of the internal drain; the
+    tool-layer `{drained}|{blockedBy}` contract is unchanged.
+- **Tests for every fix point**: integration-branch rejection at create /
+  merge-override / engine-seam / applyOne choke point; the P1-C protection
+  arm (+ the intentional semantics flip of the old "no protection target"
+  case, and the still-clearable no-commits case); `dirty_not_collected`;
+  `mergeTimeoutMs` budget wiring; and the full engine-face chain
+  (create→findActiveByTask→enqueue four-key→drain five-state) over real
+  git fixtures, modelled on the DAG side's frozen acceptance shapes.
+
+### Fixed (audit round 2 — cleanup/branch-probe tightening; all fail-closed, no semantic loosening)
+
+- **P2 — the P1-C protection arm ignored uncommitted changes.** README
+  promised "clearable bare only with no commits past base AND no uncommitted
+  work in the branch probe", but the implementation compared only commits.
+  A worktree with a clean head but a dirty tree could be bare-cleaned and the
+  uncommitted work lost. The P1-C arm now runs `git status --porcelain` on
+  the worktree: any change (or a porcelain flake) → `cleanup_protected`
+  (`force` AND `acknowledge` required), message naming "uncommitted changes
+  present". The README claim is now true.
+- **P3 — the P1-C head probe actually failed OPEN.** The comment said
+  "cannot PROVE absence of work: fail closed", but an unresolvable
+  `worktreeHead` (`null`) fell through to "not ahead" and allowed a bare
+  cleanup. It now fails `cleanup_protected` directly with a
+  "head is unresolvable" message.
+- **P3 — divergent history could bare-delete unique commits.** The P1-C
+  "ahead" test was `isAncestor(base, head)`, mapping BOTH "head behind base"
+  (safe) and "head forked off onto unrelated history" (unique work) to
+  clearable. The test is now `head !== base && !isAncestor(head, base)` —
+  only a head strictly behind base (or at base) is clearable; a divergent,
+  rebased, or unrelated head is protected.
+- **`ensureBranch` existence probe now uses `--end-of-options`** (consistency
+  with `resolveRef` / AGENTS.md red line 2; `validateBranch` already makes the
+  flag-shaped case unreachable upstream).
+- **Engine-seam idempotence never widens when `integrationBranch` is
+  omitted.** The `enqueue` idempotence scan guarded the branch comparison
+  with `integrationBranch !== undefined`, so an omitted field skipped the
+  branch dimension and could return an active job for a DIFFERENT branch on
+  the same worktree. The scan now always compares against the effective
+  branch key (`integrationBranch ?? record.integrationBranch`).
+- **`record.repoRoot` is now realpath-canonicalised on the engine-path
+  create too.** The tool path stores the canonical root (via repo-gate);
+  the engine path persisted the raw argument, so a symlinked/`..` engine
+  caller stored a value that could not string-match a canonical
+  `findActiveByTask` argument. create now realpath-normalises before
+  persisting (falling back to the raw value on realpath failure, preserving
+  prior behaviour), keeping tool- and engine-created records consistent.
+- **Explicit symlinked-repoRoot regression pin added to the test suite.**
+  Previously the realpath-normalisation above was verified only INDIRECTLY
+  on macOS (where tmpdir itself is a symlinked path); on Linux CI that
+  coverage silently disappeared. `test/worktree-service.test.js` now drives
+  `create` through a deliberately symlinked repoRoot on any platform and
+  asserts the persisted `record.repoRoot`, the `store.repos` entry, and
+  `findActiveByTask(canonicalRoot, task)` all use the canonical form.
+
+### Docs (2026-08-18, README completion ahead of the GitHub publish)
+
+README.md + README.zh.md, updated together (section-for-section aligned):
+
+- **Compatibility banner** (both languages): compatible with DSH
+  `0.1.0-rc.7` (npm latest) and `0.1.0-rc.6`; `peerDependencies:
+  ^0.1.0-rc.6` satisfies rc.7 under semver (same-version-tuple prerelease
+  rule; `0.1.1-rc.x` would not). Verified against rc.7: `defineTool` /
+  `TOOL_RUNTIME_SCHEDULER` exports intact, the new `DefineToolOptions`
+  fields all optional, 303/303 green with peers linked to rc.7.
+- **The per-call `cwd` caveat stated fully** (Why section + the
+  composition walkthrough lead + the Install bullet, en+zh): the official
+  DSH runtime's `SubagentStartRequest` has no `cwd` field, and the
+  unpatched rc.6/rc.7 runtime silently drops a per-call cwd (the child
+  inherits the parent's working directory) — the composition's
+  `subagent(cwd: P)` step is ineffective without the patches. The
+  walkthrough now requires dsh-plugin-subagents **with its
+  `patches/install.sh` run**; the Install bullet spells out that the
+  installer must be re-run after every dsh upgrade (an upgrade reinstalls
+  the pristine runtime), and that both patches apply verbatim onto rc.7
+  anchors.
+- **Cross-repo links absolutified** for the standalone GitHub repos
+  (dsh-plugin-subagents / dsh-dag-orchestrator →
+  `https://github.com/Luck9Star/<repo>`; the old `../dsh-plugin-subagents`
+  relative paths 404 outside the monorepo layout).
+- **Test count refreshed**: 295 → 303 (the suite grew; both language
+  versions).
+

package/LICENSE

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

package/README.md

@@ -0,0 +1,194 @@
+# dsh-worktrees
+
+**English** | [简体中文](README.zh.md)
+
+> Runs on DeepSeek Harness (dsh) `0.1.0-rc.6` / `0.1.0-rc.7` · Node ≥ 18 · git on PATH · MIT
+
+**Parallel agents without file fights.** Each task gets its own directory —
+a git worktree on its own branch — so several agents can edit code at the
+same time without stepping on each other. When a task finishes, its branch
+is merged back **one at a time** through a serial queue into a reviewable
+integration branch. If two tasks touched the same lines, the conflict scene
+is kept intact for you — nothing is auto-resolved or force-pushed.
+
+Six tools, zero host patches, no tool-name takeovers — install it and the
+`worktree_*` family is visible to every session.
+
+## Why
+
+Dispatch several write-task subagents in parallel and they stomp on each
+other: everyone edits the same working directory, every file is a race.
+The classical fix is git worktrees — this plugin operationalizes them for
+agent work:
+
+- `worktree_create("api-types")` → a fresh checkout at
+  `~/.dsh/worktrees/<repo>/<session>/api-types`, branch
+  `dsh-wt/<session>/<api-types>`.
+- Delegate agents there with `cwd` (via
+  [dsh-plugin-subagents](https://github.com/Luck9Star/dsh-plugin-subagents))
+  — or work there yourself.
+- `worktree_merge(id)` → uncommitted work is auto-committed, then the branch
+  merges into `dsh-wt/integration/<session>` — strictly one merge at a time,
+  so integrations can't conflict with each other mid-flight.
+
+## Install
+
+```sh
+# 1. Install into your dsh profile
+dsh plugin --profile web add dsh-plugin-worktrees   # or: add /path/to/local/checkout
+
+# 2. Restart and open a NEW session
+dsh --profile web
+```
+
+**Expected result:** a new session exposes `worktree_create`, `worktree_list`,
+`worktree_status`, `worktree_merge`, `worktree_queue`, `worktree_cleanup`.
+
+> **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
+> every tool call), then `dsh plugin --profile web add "$(pwd)"`.
+
+> **Want agents to work inside the worktrees?** The stock harness silently
+> drops a subagent's `cwd`. Install
+> [dsh-plugin-subagents](https://github.com/Luck9Star/dsh-plugin-subagents)
+> and run its `patches/install.sh` (re-run after every dsh upgrade).
+
+## Quick start
+
+The full loop — two parallel tasks, one clean merge, one conflict:
+
+```jsonc
+worktree_create({ task: "api-types" })    // → { id: id1, path: P1, branch, base_commit, … }
+worktree_create({ task: "docs-refresh" }) // → { id: id2, path: P2, … }
+
+// parallel work — each agent (or you) edits inside its own path
+subagent({ prompt: "Implement the new API types.", cwd: P1 })
+subagent({ prompt: "Refresh the docs.",         cwd: P2 })
+
+worktree_merge({ worktree_id: id1 })
+// → { state: "succeeded", integrated_commit, integration_branch }
+
+worktree_merge({ worktree_id: id2 })
+// → { state: "conflicted", conflict_files: [...],
+//     integration_worktree: "<kept scene>", resolution_hint: "…" }
+
+// resolve by hand inside the kept worktree (markers are in place), then:
+worktree_queue({ action: "list" })
+worktree_queue({ action: "resolve", job_id: "…" })   // releases the integration branch
+worktree_cleanup({ worktree_id: id1 })               // remove worktree + branch
+```
+
+## The six tools
+
+| Tool | What it does |
+| --- | --- |
+| `worktree_create` | New worktree + dedicated branch for a task. Returns `path` (hand it to `cwd`), `branch`, `base_commit`, `integration_branch`. |
+| `worktree_list` | List worktrees for a repo (optional: include retained conflict scenes), plus a merge-queue summary. |
+| `worktree_status` | One worktree: HEAD, dirty state, per-file changes, ahead-of-base, current merge job. |
+| `worktree_merge` | Auto-commit uncommitted work, then enqueue + merge into the integration branch. Five possible outcomes (below). |
+| `worktree_queue` | Inspect the queue; `resolve` / `retry` / `cancel` a job. |
+| `worktree_cleanup` | Remove a worktree (and its branch, unless `keep_branch`). Refuses to destroy unmerged work without double confirmation. |
+
+### Merge outcomes
+
+| `state` | Meaning |
+| --- | --- |
+| `succeeded` | Merged; `integrated_commit` on the integration branch. |
+| `conflicted` | Conflicts. The integration worktree is **kept** with markers in place; the job holds the branch until you `resolve` or `retry`. |
+| `queued` | Enqueued behind other merges (`queued_ahead` tells you how many). |
+| `no_changes` | Clean tree at base — nothing to integrate (normal, not an error). |
+| `failed` | Hard failure (e.g. dirty tree with `autoCollect: false` → `dirty_not_collected`). |
+
+### Conflicts, the short version
+
+Nothing is auto-resolved, nothing is rebased, nothing is force-pushed. A
+conflicted merge keeps the scene (a retained worktree with conflict markers),
+tells you the files, and **blocks that integration branch** until you:
+edit the files inside the kept worktree and `worktree_queue(action:
+"resolve")`, or `action: "retry"` to re-queue the merge, or abandon.
+
+## Safety, built in
+
+- **Unmerged work is hard to lose.** Cleanup of a worktree whose commits
+  never made it to the integration branch requires **two** independent
+  confirmations (`force: true` **and** `acknowledge: true`); otherwise it
+  refuses with evidence. A merged worktree cleans up without ceremony.
+- **Repo gate, fail closed.** Worktrees are only created inside the session
+  cwd subtree, registered workspaces, or `allowedRoots` — there is no
+  any-root switch. Branch names are validated by git itself.
+- **Local only.** The plugin can merge but never push/fetch/clone — results
+  stay on the local integration branch for a human to review and push.
+- **Dirty trees are handled.** `autoCollect: true` (default) commits
+  uncommitted work (including untracked files) before merging. Turn it off
+  and a dirty tree stops the merge with a clear error instead.
+- **Restart-safe.** On startup, worktrees whose repo/path vanished are
+  marked `orphaned`, in-flight merges are failed with a note — marking only,
+  no destructive deletes.
+
+## Configuration
+
+Optional — everything below has a working default. Keys live on the plugin's
+row in your profile's `cordis.patch.yml`; unknown keys fail loudly at startup.
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `worktreeRoot` | `~/.dsh/worktrees/` | Root directory for all task worktrees. |
+| `maxWorktrees` | `16` | Cap on non-terminal worktrees across repos. |
+| `defaultBaseRef` | `HEAD` | What new task branches start from (always resolved to a concrete commit). |
+| `autoCollect` | `true` | Auto-commit uncommitted work before merging. |
+| `gitTimeoutMs` / `mergeTimeoutMs` | `15000` / `120000` | Per-git-command / merge-step timeouts. |
+| `allowedRoots` | `[]` | Extra repo roots the gate admits. |
+| `requireWorkspaceRegistration` | `true` | Also admit registered workspaces (disable to rely on session-cwd + `allowedRoots` only). |
+| `statePath` | `~/.dsh/dsh-worktrees/state.json` | State file (atomic, owner-only writes). |
+| `retainJobHistory` | `200` | Terminal merge-job records kept. |
+| `register.*` | `true` | Per-tool switches. |
+
+## Works well with
+
+- [dsh-plugin-subagents](https://github.com/Luck9Star/dsh-plugin-subagents)
+  — its per-call `cwd` is the join point: pass `worktree_create`'s `path`
+  straight to the subagent and it writes inside the worktree.
+- [dsh-dag-orchestrator](https://github.com/Luck9Star/dsh-dag-orchestrator)
+  — this plugin exposes a `worktreesEngine` service the orchestrator probes
+  for, enabling `worktree:` task isolation and `merge` nodes in DAGs with
+  zero extra wiring.
+
+## Boundaries & troubleshooting
+
+- **One repo, one dsh session for merges.** The queue is an in-process
+  chain; two hosts merging the same repo concurrently is not supported.
+- **`cwd` ignored?** Stock harness drops it — install dsh-plugin-subagents
+  and run its `patches/install.sh`.
+- **`active_job_exists` error** — an earlier conflicted job holds the
+  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.
+
+## Development
+
+```sh
+npm install && npm run setup:peer   # link the running harness's peers
+npm test                            # node --test, real local git fixtures — no network or remotes
+npm run lint
+```
+
+Design record: [docs/DESIGN.md](docs/DESIGN.md).
+
+## References & credits
+
+- **git worktree** — the mechanism everything here is built on.
+- **task-weaver** (`packages/workspaces/`) — the core engine (git port,
+  merge queue, conflict-scene retention) is ported from it.
+- [dsh-plugin-subagents](https://github.com/Luck9Star/dsh-plugin-subagents)
+  and [dsh-dag-orchestrator](https://github.com/Luck9Star/dsh-dag-orchestrator)
+  — the companion plugins this is designed to compose with.
+
+## Security
+
+See [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE)