dsh-tower 2.1.0 → 2.4.0

package/README.md

@@ -127,19 +127,26 @@ tower_teardown  repoRoot=D:\work\repo
 
 ## 组件模型
 
-本 bundle 采用 **all-or-nothing**：`cordis.patch.yml` 只插入一个 `tower-bundle`
-`cordis:group` 行，Host 插件、skills、worker/reviewer preset 都是它的内部 section。插件页只应把
-这个 group 当作一个组件；关闭它时四个 section 一起关闭，不会留下指向已消失 `tower_*` 工具的
-orphan preset/skill。不要再把子行单独启停。
-
-进入 Tower 模式与 `tower_plan` 前会校验两个 preset 是否已注册；缺失时直接以 `preset-missing`
-拒绝（并在消息中点名 `preset-tower-worker` / `preset-tower-reviewer`），不会先完成规划/派发再在
-review/merge 阶段死锁。
+本 bundle 采用 **强制 host 锚点 + 可单独启停的可选行**（#121）：`cordis.patch.yml` 插入顶层
+`tower` group（挂载 Host 插件与强制的 `preset-tower-worker`），随后是可选组件 `tower-skills`、
+`tower-batch`、`tower-import`、`tower-leases`、`tower-tests`、`tower-hmr`（随包关闭）与
+`preset-tower-reviewer`。在插件页关闭某一行，只会移除该能力；模式、规划工具、`tower_status`
+与其余工具继续工作。
+
+进入 Tower 模式与 `tower_plan` 前会校验必需的 preset。worker preset 是强制依赖；reviewer
+preset 只在 `review.requireReview` 为 true 时必需，因此审查可选时允许关闭 reviewer 行，强制审查
+开启时会以带解释的 `preset-missing` 锁定。`tower-tests` 关闭且 `gates.requireTests:true` 时同样
+拒绝。`tower_doctor` 与 `tower_recover` 不是组件、也没有配置键：任何配置都会注册它们（#122）。
+
+原则 11（[PRINCIPLES.md](PRINCIPLES.md)）与
+[ADR 0005](docs/adr/0005-component-surface.md) 要求：只有关闭后仍不破坏其余能力的 capability
+才能成为组件；host、健康检查、恢复通道、审查契约与合并门禁永远不是开关。逐键答案见生成的
+[组件表面](docs/reference/component-surface.md)，由 `npm run docs:check:components` 强制。
 
 ## 配置
 
 ```yaml
-- id: tower
+- id: tower-host
   name: 'dsh-tower'
   config:
     section: '（可选，兼容别名）覆盖 Tower 模式系统提示文案'
@@ -164,18 +171,18 @@ review/merge 阶段死锁。
 - 代码中 `mode.allowAgentControl` 默认 `true`；随包 `cordis.patch.yml` 也显式设为 `true`：模型可在用户意图/任务状态明确时自行进出，但必须给出理由；设为 `false` 时只有人类能切换。随包 patch 还默认开启 `mode.workspaceLock`（单活塔）、`send.interruptDefault`、`init.autoGitInit`，并把 `spawn.staleMs` 设为 15s。
 - `/tower base <branch>` 可设置会话级 init base 偏好；`/tower on` 会清除活跃 plan mode（`mode.planModePolicy:"refuse"` 则拒绝进入），保证 plan/tower 互斥。
 - 仓库级配置：在 `<git-common-dir>/dsh-tower/config.json`（通常是 `.git/dsh-tower/config.json`）放入同样的 JSON 结构，可覆盖 `review`/`merge`/`worktrees`/`spawn`；优先级为代码默认 < profile < 仓库配置 < 工具参数。`mode.*` 属于会话级，只在 profile 生效。
-- 所有键与默认值见 [docs/reference/config.md](docs/reference/config.md)；未知顶层键会被拒绝（防止拼写错误静默失效），嵌套分组内的未知键会被忽略。工具错误码见 [docs/reference/errors.md](docs/reference/errors.md)。
+- 所有键与默认值见 [docs/reference/config.md](docs/reference/config.md)；未知键（顶层与分组内）都会被拒绝，防止拼写错误静默失效。工具错误码见 [docs/reference/errors.md](docs/reference/errors.md)。
 
-## 工具（27 个核心）
+## 工具（29 个：22 个核心 + 7 个可选）
 
 `tower_init` · `tower_plan` · `tower_mission` · `tower_status` · `tower_spawn` · `tower_roster` · `tower_adopt` · `tower_diff` · `tower_send` · `tower_inbox` · `tower_complete` · `tower_interrupt` · `tower_finding` · `tower_findings` · `tower_review` · `tower_preflight` · `tower_merge` · `tower_rebase` · `tower_teardown` · `tower_mode` · `tower_doctor` · `tower_recover` · `tower_test` · `tower_batch` · `tower_resource` · `tower_import_legacy` · `tower_legacy_map`
 
-`tower_control` 默认注册（`allowAgentControl:true`）；设为 `false` 可禁用；`tower_reload` 在 `dev.hotReload`（默认 true）时注册，无 HMR 服务调用会返回 `reload-unavailable`（因此最多 29 个工具）。mission 级工具同时接受 `id` 作为 `missionId` 的别名；`task_done`/`taskDone` 等 snake/camel 写法均可。
+上面列出的是 22 个核心工具加 5 个由组件行拥有的可选工具。`tower_control` 是第 6 个可选工具，默认注册（`allowAgentControl:true`）；设为 `false` 可禁用。`tower_reload` 是第 7 个，仅在 `tower-hmr` 组件行开启时注册（随包关闭），无 HMR 服务调用会返回 `reload-unavailable`（因此最多 29 个工具：22 个核心 + 7 个可选）。`tower_doctor` 与 `tower_recover` 属于核心：任何配置都会注册它们（#122）。mission 级工具同时接受 `id` 作为 `missionId` 的别名；`task_done`/`taskDone` 等 snake/camel 写法均可。
 
 ## 安全与约束
 
 - **门禁不全绿不合并。** `tower_preflight` 是只读检查，返回稳定的 blocker code；存在 blocker 时 `tower_merge` 拒绝合并。
-- **审查绑定提交。** 开启 `review.requireReview` 时，审查后分支 tip 变化会报 `tip-moved`，必须重新审查；reviewer 使用只读 preset，若在审查期间改动分支，提交审查会被拒绝。
+- **审查绑定提交。** 开启 `review.requireReview` 时，审查后分支 tip 变化会报 `tip-moved`，必须重新审查；reviewer 使用只读 preset，若在审查期间改动分支，提交审查会被拒绝。非 clean 的一轮审查会让 mission 回到 active，此后其他 route 仍可为同一 reviewed tip 提交结论并追加到同一轮；依赖为 `completed` 的 survey 视为已满足（build 依赖仍需 merged）。
 - **scope 强制。** mission 只能修改其 scope glob 匹配的文件，越界会以 `out-of-scope` 阻止合并。
 - **worktree 归属。** 脏工作树、运行中的 worker、已关闭 mission 的分支都会阻止合并或 teardown。
 - **goal 隔离。** 进入 Tower 模式会暂停活跃 goal 并记录；退出不会自动恢复，需要你自行恢复。
@@ -199,8 +206,8 @@ worker 与 reviewer 是使用内置 `tower-worker` preset 的普通 DSH 子代
 
 | 路径 | 内容 |
 |---|---|
-| `package.json`、`cordis.patch.yml` | bundle 清单与 loader patch（单个 `tower-bundle` group，内含 Host、skills 与两个 preset） |
-| `index.js`、`lib/`、`worker.js` | Host 入口、协议实现、worker preset 策略 |
+| `package.json`、`cordis.patch.yml` | bundle 清单与 loader patch（强制 `tower` host group + 可选能力行） |
+| `index.js`、`host/`、`adapters/`、`app/`、`domain/`、`ports/`、`tools/`、`worker.js` | Host 入口；`domain/` 纯核心；`ports/` 契约；`adapters/` 唯一 I/O；`app/` 用例；`host/` 组合根与会话胶水；`tools/` 每工具一个 handler；worker preset 策略 |
 | `locale/`、`icon.svg` | 本地化与图标 |
 | `tests/` | 纯函数、协议 e2e、插件级测试；可选的真实 Web 运行时脚本 |
 | `ui-bundle/` | 可选 Client 小挂件（Tower 工具卡片、Tower·on 状态 chip、模式感知的 disabled 行、dock 摘要、临时 overlay 状态条），默认不安装 |
@@ -212,7 +219,7 @@ worker 与 reviewer 是使用内置 `tower-worker` preset 的普通 DSH 子代
 npm test        # node --test tests/*.test.mjs
 ```
 
-热重载开发：`npm run dev:hmr` 把本仓库加入当前 profile 的 HMR watch root（需重启 DSH 一次），之后编辑 `lib/` 代码可用 `/tower reload` 或自动 watch 生效；详见 [docs/guide/hot-reload.md](docs/guide/hot-reload.md)。
+热重载开发：`npm run dev:hmr` 把本仓库加入当前 profile 的 HMR watch root（需重启 DSH 一次），之后编辑 `host/`、`adapters/`、`app/`、`domain/` 代码可用 `/tower reload` 或自动 watch 生效；详见 [docs/guide/hot-reload.md](docs/guide/hot-reload.md)。
 
 离线套件不需要 DSH 进程，只在系统临时目录创建一次性 Git 仓库。隔离 Web 运行时检查、模型驱动验收和会话诊断脚本见 `tests/README.md`。
 
@@ -222,18 +229,21 @@ npm test        # node --test tests/*.test.mjs
 
 | Job | 声明 | 证据 |
 |---|---|---|
-| `test (22)`、`test (24)`（Ubuntu） | 离线套件、文档一致性、生成文档、发布文件清单、架构、类型与 domain 纯度全部成立 | `npm test`、`npm run docs:check`、三个 `docs:check:generated*`、`pack:check`、`architecture:check`、`types:check`、`domain:check` |
+| `test (22)`、`test (24)`（Ubuntu） | 离线套件、文档一致性、生成文档、发布文件清单、架构、类型与 domain 纯度全部成立 | `npm test`、`npm run docs:check`、五个 `docs:check:generated*`（含生成的类型词汇表）、`pack:check`、`architecture:check`、`types:coverage`、`types:strict:check`、`types:check`、`domain:check` |
 | `test (22, windows)`（`windows-latest`，非必需检查） | 同一套离线套件与离线 gates 在真实 Windows 文件系统上成立；路径大小写、`pwsh` shell、rename/unlink 重试都不是只在 Linux 上被假设 | `npm test` + 与 Ubuntu 相同的离线 gates（不跑 release/coverage） |
 | `test` 的 `Coverage (Node 22)` 步骤 | 覆盖率在 CI 中真实测量（只报告，不设阈值、不加徽章） | `npm run test:coverage` |
 | `test` 的 `Release check`（Node 22）步骤 | tag 是一种声明：版本已越过上一个版本 tag、推送的 tag 是 `v<version>`、CHANGELOG 带有发布内容 | `npm run release:check` |
 | `mount`（Node 22） | 打出的 tarball 经 plugin CLI 装进一次性 profile 后，真实 loader 挂载并注册了 bundle 声称的表面 | `npm run smoke:mount` |
 | `mount-fixtures`（Node 22，非必需检查） | mount smoke 仍会因正确的种子失败而变红（改名一个工具 id、删除 skills 段），三次运行共用一次缓存的 host 安装 | `npm run smoke:fixtures -- --host-dir <缓存的 host>` |
+| `live (<固定 host 版本>)`（nightly/手动，非必需检查） | 浏览器 live suite 在固定 host 版本矩阵上仍能驱动真实 Web 运行时；push/PR 只做无浏览器的环境与解析检查 | nightly 跑 `npm run test:live -- --script nightly`；push 跑 `npm run test:live -- --check` |
 
 `test` 的三条 leg 在 job 内用 `matrix.name` 固定各自的 context 字符串：`test (22)`、`test (24)` 与新增的 `test (22, windows)`。前两条是 `main` 的必需检查，名字逐字节不变；把 `os` 直接塞进 matrix 会把它们改名成 `test (22, ubuntu-latest)`，保护规则将永远等不到该 context，所以矩阵用显式 `include` + `name`。Windows leg 只跑 Node 22 和离线套件/离线 gates（无浏览器、无 live suite、无 release/coverage），与现有 job 并行，不延长关键路径。它目前不是必需 context：让它变绿是本 issue 的验收，把它加入保护设置是 #94 的人工步骤。
 
+live suite 需要下载浏览器并真实启动 host，因此移出 push/PR，改为 nightly `schedule`（另支持 `workflow_dispatch`），在固定 host 版本矩阵上运行；它的输出第一行打印解析后的 `DSH_HOME` 与 host 版本。push 上只保留 `--check`（环境 + Playwright 解析，无浏览器）。Playwright 由 `tests/live/package-lock.json` 固定，root 的 `npm ci` 不下载浏览器。
+
 `tests/platform.test.mjs` 用注入的 `platform`/`rename`/`unlink` 在任意 OS 上同时断言 win32 与 POSIX 两条分支；唯一需要真实 Windows 的“rename 覆盖被打开的目标文件”用例在 Linux 上以 `# SKIP` 计入 TAP（`tests 11`、`skipped 1`），而不是静默消失。macOS 不单设 runner：它与 Linux 走同一条 POSIX 分支，这是 #86 的非目标。
 
-`mount` 断言一次性 profile 的**已加载表面**，而不是 `cordis.patch.yml` 的文本：29 个 `tower_*` 工具（27 个 `tools/*.js` 模块 + `tower_mode` / `tower_control`）、3 个内置 skill、`tower-worker` / `tower-reviewer` 两个 preset、`/tower` 命令，以及唯一一个顶层 `tower-bundle` group 行（#66）。它不调用模型、不打开浏览器。在维护者的 Windows 机器上实测：host 冷装（含安装）约 100 秒，host 已缓存约 85 秒；CI 中该步骤上限为 3 分钟（`timeout-minutes: 3`），`mount` job 上限 5 分钟。红叉会打印解析后的 profile 路径、host build、已加载计数与每一条未满足的声明。
+`mount` 断言一次性 profile 的**已加载表面**，而不是 `cordis.patch.yml` 的文本：随包 profile 加载 28 个 `tower_*` 工具（27 个 `tools/*.js` 模块 + `tower_mode` / `tower_control`，减去因 `tower-hmr` 随包关闭而不注册的 `tower_reload`；所有可选能力行全开时为 29 个）、3 个内置 skill、`tower-worker` / `tower-reviewer` 两个 preset、`/tower` 命令、一个顶层 `tower` host group 以及可选的顶层能力行（`tower-hmr` 随包关闭）。它不调用模型、不打开浏览器。在维护者的 Windows 机器上实测：host 冷装（含安装）约 100 秒，host 已缓存约 85 秒；CI 中该步骤上限为 3 分钟（`timeout-minutes: 3`），`mount` job 上限 5 分钟。红叉会打印解析后的 profile 路径、host build、已加载计数与每一条未满足的声明。
 
 host build 只固定在一个地方：`scripts/mount-smoke/host.json`，`COMPATIBILITY.md` 最新一行由单元测试强制与它一致，发布时不再各写一遍。`npm run smoke:fixtures` 用两种种子失败（改名一个工具 id、删除 skills 段）证明 smoke 会以正确原因变红；CI 中它作为非必需的 `mount-fixtures` job 运行，control 与两个种子通过 `--host-dir` 共用一次缓存的 host 安装（本机热跑约 2 分钟）。
 

package/SECURITY.md

@@ -42,6 +42,12 @@ gh api repos/louifinn/dsh-tower/branches/main/protection \
 
 Please do **not** publish exploit details in a public issue. Open a minimal issue titled `security: request private contact` describing only the impact category (for example “merge gate bypass”), and a maintainer will arrange a private channel. Include the affected version and, if possible, a minimal reproduction in the private follow-up.
 
+A security fix that shipped and then stopped working is a regression, not an
+ordinary bug. Use the six-field record in
+[docs/operations/incident.md](docs/operations/incident.md) (including the
+`Regression test:` path) once the private report is resolved; the public closure
+still carries no exploit detail.
+
 ## Supported versions
 
 Security fixes target the latest released `2.x` line (currently `2.0.4`). Older pre-release snapshots

package/{lib → adapters}/archive.js

@@ -12,7 +12,7 @@
 // mission id, so a crash between the two files is recoverable on the next
 // mutation instead of losing a mission.
 import path from 'node:path'
-import { fsp } from '../adapters/store-fs.js'
+import { fsp } from './store-fs.js'
 import {
   ARCHIVE_VERSION,
   archiveDocumentError,

package/{lib → adapters}/caseSensitivity.js

@@ -13,7 +13,7 @@
 //          stat failure). "Unknown" is deliberately not "case-sensitive": init
 //          keeps working and `tower_doctor` reports the safe default.
 import path from 'node:path'
-import { fsp } from '../adapters/store-fs.js'
+import { fsp } from './store-fs.js'
 
 /** Prefix is public so tests and support code can recognise a leaked probe. */
 export const CASE_PROBE_PREFIX = '.tower-case-probe-'

package/adapters/default.js

@@ -1,12 +1,53 @@
-// Default composition root for Tower dependencies (#50).
-import * as store from '../lib/store.js'
-import * as vcs from '../lib/git.js'
-import * as caseSensitivity from '../lib/caseSensitivity.js'
+// Default composition root for the Tower ports (#50, #69).
+//
+// This module is the one place where the concrete adapters (node:fs,
+// node:child_process) are turned into the plain deps object the app layer
+// takes. `createDefaultDeps()` is called once by the host entry (index.js); the
+// app never imports an adapter. Tests and embedders use the memoised
+// `defaultDeps` (or host/tower.js) so the process has exactly one adapter set.
+import crypto from 'node:crypto'
+import * as archive from './archive.js'
+import * as caseSensitivity from './caseSensitivity.js'
+import * as config from '../host/config.js'
+import { loadStateFile } from './stateFile.js'
+import * as ownership from './worktreeOwnership.js'
+import { createStorePort } from './store-fs.js'
+import { createVcsPort } from './vcs-git.js'
+import { NOOP_EVENT_PORT } from '../ports/events.js'
 
-export const defaultDeps = {
-  store,
-  vcs,
-  caseSensitivity,
-  clock: { now: () => Date.now() },
-  ids: { uuid: () => crypto.randomUUID() },
+/**
+ * Assemble a dependency object implementing every port in ports/.
+ * @param {Partial<Record<'store'|'vcs'|'config'|'state'|'archive'|'ownership'|'caseSensitivity'|'clock'|'ids'|'events', any>>} [overrides]
+ * @returns {Record<string, any>}
+ */
+export function createDefaultDeps(overrides = {}) {
+  const store = createStorePort()
+  return {
+    store,
+    vcs: createVcsPort(),
+    config: {
+      runtimeConfig: config.runtimeConfig,
+      resolveRepoConfig: config.resolveRepoConfig,
+    },
+    state: { loadStateFile },
+    archive: {
+      readIndex: archive.readArchiveIndex,
+      readEntry: archive.readArchivedEntry,
+      writeEntries: archive.writeArchiveEntries,
+    },
+    ownership: {
+      assertOwnership: ownership.assertOwnership,
+      canonicalPath: ownership.canonicalPath,
+    },
+    caseSensitivity: { detect: caseSensitivity.detectCaseSensitivity },
+    clock: { now: () => Date.now() },
+    ids: { uuid: () => crypto.randomUUID(), shortHash: store.shortHash },
+    // The host entry replaces this with the Cordis emitter; default deps (and
+    // tests/embedders) keep the no-op channel so events never fail a tool.
+    events: NOOP_EVENT_PORT,
+    ...overrides,
+  }
 }
+
+/** The single process-wide default adapter set. */
+export const defaultDeps = createDefaultDeps()

package/{lib → adapters}/git.js

@@ -1,6 +1,6 @@
 import { TowerToolError } from '../domain/errors.js'
 // Minimal git port: array arguments only, bounded output, no shell.
-import { execFile } from '../adapters/vcs-git.js'
+import { execFile } from './vcs-git.js'
 import path from 'node:path'
 
 const GIT_TIMEOUT_MS = 15000

package/{lib → adapters}/leases.js

@@ -11,7 +11,7 @@
 // Fail-closed protocol: a held, expired, or token-mismatched lease is reported,
 // never silently taken over. Only the token holder may release a lease, and
 // releasing an expired lease requires an explicit `force: true`.
-import { fsp } from '../adapters/store-fs.js'
+import { fsp } from './store-fs.js'
 import path from 'node:path'
 import crypto from 'node:crypto'
 

package/{lib → adapters}/legacy.js

@@ -9,7 +9,7 @@
 //
 // `validateLegacyMap` is the audit-only mapping check: a map is a record that
 // legacy id X corresponds to DSH mission Y. It never adopts or restores work.
-import { fsp } from '../adapters/store-fs.js'
+import { fsp } from './store-fs.js'
 import path from 'node:path'
 import crypto from 'node:crypto'