@twinsearth/w2m-dsh-plugin 1.3.1 → 1.4.0

package/docs/COLLAB/M7-METRICS-ACCEPTANCE.md

@@ -0,0 +1,263 @@
+# M7 指标与验收设计规格
+
+> 状态：**设计稿**。只定义指标口径、验收体系与门禁，不含实现。
+> 版本：`1.3.8-beta.*`（GitHub prerelease，不入 npm）。
+> 上游：`docs/MULTI-MACHINE-COLLABORATION-PLAN.md` M7；覆盖 M1–M6 与三个模型（v1.4.x）的验收。
+
+---
+
+## 1. 目标与非目标
+
+### 目标
+
+1. **每个能力都必须能被真实任务触发**：不允许"单测过了就算完成"；验收记录必须能追溯到具体 task_id、机器、时间、ledger 区间。
+2. **负向测试是必选项**：每个模块的错误码都必须有一条自动化用例证明"该拒绝时确实拒绝，且没有副作用"。
+3. **指标统一口径**：任务成功率、重试/重派、分块断点、outbox、事件延迟、锁冲突、审查时效、合并冲突、P2P 成功率等，全部由 relay 真实数据计算，不靠客户端自报。
+4. **门禁可执行**：preflight 增加"验收证据存在且可校验"的检查；beta 与 stable 的验收门槛不同，写死为门禁而不是口头约定。
+5. **证据可留存、可复现**：验收产物（evidence）进仓库固定目录，含命令、结果、sha、ledger 区间，后续版本可回放核对。
+
+### 非目标
+
+- 不做外部 APM/监控平台接入（本版本只暴露指标 + 本地快照）。
+- 不做性能压测基线（M7 只做正确性与混沌验收；吞吐性能另立）。
+- 不追求 100% 自动化真实机器测试（允许"人工执行 + 证据上传"，但证据格式与校验必须统一）。
+
+---
+
+## 2. "真实任务可触发"的定义（验收硬标准）
+
+一条能力算通过，必须同时满足：
+
+```
+1. 存在一个真实 task_id（relay 可查、结果可复现）
+2. 涉及 ≥1 台真实机器（不是进程内 mock；单机能力可 1 台）
+3. 结果通过 relay 聚合可验证（outcome/status/字段断言）
+4. sanitized 证据入仓库：docs/acceptance/<version>/<case>.json + 关联 artifact
+5. 负向用例证明"拒绝路径正确且无副作用"（head/任务/文件未变）
+6. 能在另一台机器/另一时间重跑（命令、版本、前置条件齐全）
+```
+
+证据文件格式（统一）：
+
+```json
+{
+  "version": "1.3.2-beta.1",
+  "case": "M1-UPDATE-EMPTY-ALLOWLIST",
+  "kind": "positive|negative|chaos",
+  "requirement": "空 allow-list 机器远程升级",
+  "machines": ["1c14d7d2-…", "6c92b251-…"],
+  "commands": [["node", "bin/w2m-maintenance.mjs", "--only-check"]],
+  "task_id": "01M6…",
+  "ledger_seq": [100, 104],
+  "result": { "outcome": "ok", "assertions": { "version": "1.3.2-beta.1" } },
+  "artifacts": [{ "sha256": "…", "bytes": 1234 }],
+  "executed_at": "2026-10-21T14:00:00Z",
+  "executor": "lead|human",
+  "reproduce": "docs/acceptance/<version>/RUNBOOK.md#M1-UPDATE-EMPTY-ALLOWLIST"
+}
+```
+
+---
+
+## 3. 指标口径（统一由 relay 计算）
+
+### 3.1 任务与调度
+
+```
+wm_tasks_total{status, mode}
+wm_task_duration_ms{status, mode}         p50/p95/p99（直方图）
+wm_task_requeued_total                   重派发次数（reconnect/lease 过期）
+wm_lease_expired_total{reason}
+wm_result_duplicate_total                重复结果被去重的次数（应为 0 效果、>0 收到）
+wm_dependency_released_total
+```
+
+### 3.2 授权（M1/M2）
+
+```
+wm_grant_issued_total{machine_scope}
+wm_grant_denied_total{code}              各 GRANT_* 拒绝码计数
+wm_grant_expired_total
+wm_maintenance_requests_total{action,outcome}
+wm_maintenance_rollback_total
+```
+
+### 3.3 数据面（M3/M6）
+
+```
+wm_blob_upload_sessions_total{state}
+wm_blob_chunks_total{retried}
+wm_blob_resume_total
+wm_blob_bytes_total{mode}
+wm_blob_sha_mismatch_total
+wm_agent_outbox_depth
+wm_agent_outbox_dropped_total
+wm_worktree_active / wm_worktree_cleaned_total
+wm_merge_queue_depth{project,branch}
+wm_merge_conflict_total
+wm_merge_merged_total
+```
+
+### 3.4 协作（M4/M5）
+
+```
+wm_project_events_total{type}
+wm_event_lag_ms{client}                  客户端应用时间 - 事件时间（p95）
+wm_sse_reconnects_total
+wm_lock_acquired_total{kind} / wm_lock_conflict_total / wm_lock_force_released_total
+wm_review_pending / wm_review_decision_total{decision}
+wm_review_latency_ms                     创建→首个结论（p95）
+wm_notification_sent_total{kind} / wm_notification_digest_total / wm_notification_unread
+```
+
+### 3.5 传输（M6）
+
+```
+wm_p2p_push_attempts_total / wm_p2p_push_success_total / wm_p2p_fallback_total
+wm_p2p_crypto_refusals_total
+wm_relay_restarts_total（relay 启动时从持久化文件推断或写入）
+```
+
+### 3.6 暴露方式
+
+- `GET /metrics`（Prometheus 文本格式，已有路由形态可复用）或 `w2m_stats` 聚合视图。
+- 指标只存计数器/直方图聚合（内存 + 定期快照到 state），不存原始事件。
+- 标签基数限制：machine_id 可入标签，task_id 不入（避免爆炸）。
+
+---
+
+## 4. 验收体系分层
+
+| 层 | 名称 | 运行环境 | 强制程度 |
+|---|---|---|---|
+| L0 | 单元/纯函数 | 任意 | beta 必过（已有 node --test） |
+| L1 | 组件集成 | 本地 fake relay + 真 agent 进程 | beta 必过 |
+| L2 | 真实任务 | 编队真机（jp-shared / TwinsEarth / macmini / ToFuture） | beta 子集、stable 全量 |
+| L3 | 混沌 | 本地/真机断网、杀进程、重启、配额 | beta 抽测、stable 必过 |
+| N | 负向矩阵 | 随每模块交付 | 全部版本必过 |
+
+---
+
+## 5. 验收矩阵（按版本）
+
+| 版本 | 模块 | L2 正向（真实任务） | N 负向（必须自动化） | L3 混沌 |
+|---|---|---|---|---|
+| 1.3.2-beta | M1 | 空 allow-list 机器远程 update/restart/diag；relay 升级 | 未签/错签/过期/换机/重放/越界 action/sha 不符/包内版本不符/篡改 | 升级中断回滚；relay 重启后恢复 |
+| 1.3.3-beta | M2 | 空 allow-list 执行 node -e；多机 grant；撤销生效 | GRANT_* 全矩阵；重放；超 max_uses；旧 agent | 撤销后立即拒绝；重启后计数保留 |
+| 1.3.4-beta | M3 | 两机并行改不同文件 → 合并；同文件 → MERGE_CONFLICT | 篡改 patch/写 .git/非合并器/force push/中断恢复 | 合并中断后锁恢复；重放幂等 |
+| 1.3.5-beta | M4 | 双客户端同任务板/制品/决策；断线补齐 | 非成员/observer 越权/seq 缺口/重复事件 | relay 重启 seq 连续 |
+| 1.3.6-beta | M5 | 锁冲突/过期/强制释放；审查通过/拒绝；离线通知补齐 | 并发抢锁/非 holder/自审/重复结论/通知风暴 | 锁过期重入；通知限流不丢 |
+| 1.3.7-beta | M6 | 40MiB 分块上传下载；断点续传；outbox 恢复 | BLOB_* 全矩阵；outbox 满；P2P 明文回落 | relay/agent 重启；断网 30/60s |
+| 1.3.8-beta | M7 | 验收证据可执行、指标可读；跑一遍前六项 | 证据缺失/伪造/过期 → preflight 拒绝 | 指标在混沌下保持单调/无倒挂 |
+
+---
+
+## 6. 测试与混沌基础设施
+
+### 6.1 本地
+
+- **fake relay**（已有 `startFakeRabbit`）：L1 用；扩展支持 blob-sessions/项目房间路由。
+- **双机 harness**（已有 `test/agent.test.mjs` 与部署脚本）：L1 两 agent + 一个 relay。
+- **chaos 工具**（新增，纯 JS 优先，避免外部依赖）：
+  - `pause(agent)` / `kill(agent)` / `kill relay`（进程级）
+  - 网络中断：本地代理（node net server 转发，可主动断开）模拟断网/丢包/慢速
+  - 时钟偏移：注入 `now()`（部分模块已支持）
+  - 配额耗尽：直接填满 blob/outbox/锁上限
+- 所有 chaos 用例必须有确定性断言（轮询超时而非 sleep 固定值）。
+
+### 6.2 真机（L2）
+
+- 机器池：`jp-shared`（Linux）、`TwinsEarth`（Windows）、`macmini`（macOS）、`ToFuture`（Windows）。
+- 前置：M1/M2 完成后通过 grant 授权执行；不能在验收中放宽 allow-list（验收本身要证明"不放宽也能做"）。
+- 数据安全：M3 验收使用**临时测试仓库**（本地 bare 或专用 demo repo），不碰本插件发布仓库的 main。
+- 清理：验收后停服务/删临时 worktree/撤销 grant，脚本化。
+
+---
+
+## 7. 门禁集成（preflight 扩展）
+
+新增检查项（注册进 preflight 的 15 项清单，替换/扩展现有"declared suite"）：
+
+```
+1. acceptance-evidence：docs/acceptance/<current_version>/ 存在；每个 case JSON 通过 schema 校验；
+   task_id 能在当前 ledger/relay 中查到（或标记 archived 并带哈希）；artifact sha 可下载且匹配。
+2. negative-matrix：每个已声明错误码在证据中有至少一条 negative case；缺一个即 RED。
+3. metrics-smoke：/metrics（或 stats）包含全部声明指标名；无重复/无非法标签。
+4. chaos-lite（stable 门禁）：本地 chaos 用例全过；beta 只需抽测并记录。
+5. docs-claims：与现有 claims 检查合并，新增文档必须被索引（§9）。
+```
+
+beta / stable 门槛：
+
+```
+beta  ：L0+L1 全过 + 本版本 L2 正向至少 1 条 + 对应 N 负向全过 + 证据入库
+stable：beta 全部 + L2 全量 + L3 本版本相关用例全过 + 上版本回归
+```
+
+---
+
+## 8. 验收证据的保存与索引
+
+```
+docs/acceptance/README.md                 索引（版本 → case 列表 → 状态）
+docs/acceptance/<version>/RUNBOOK.md      可复现步骤（命令/前置/期望）
+docs/acceptance/<version>/<case>.json     机器可读证据
+docs/acceptance/<version>/artifacts/      可选小产物（大产物只存 sha，走 blob/ release）
+```
+
+规则：
+
+- 证据必须由 `scripts/acceptance.mjs`（新增）生成骨架，人工填结果后校验，避免手写非法 JSON。
+- 每次发布（beta/stable）时，CHANGELOG 对应条目必须引用该版本的 acceptance 目录。
+- 证据随版本冻结；后续修改以新 case 追加，不改历史。
+
+---
+
+## 9. 文档与声明的一致性
+
+- 新文档（含本系列设计稿）必须登记进 `docs/acceptance/README.md` 或 `docs/INDEX`（实现时按现有 claims 机制选择），否则门禁拒绝。
+- **能力级别口径修正**（M7 一并落地）：
+  - "多机派发/聚合"（已实现）
+  - "多机协同开发"（M1–M6 完成后才算）
+  - "多客户端共享项目"（M4–M5 完成后才算）
+- README/CHANGELOG 不再用"多机协同"泛称覆盖未完成能力。
+
+---
+
+## 10. 风险与对策
+
+| 风险 | 对策 |
+|---|---|
+| 真机验收不可重复（机器掉线/环境漂移） | 证据带机器快照（版本/OS/caps）；允许同 case 重跑覆盖（保留历史）；关键 case 至少两台机器 |
+| 测试变慢导致门禁不可用 | 分层：beta 只跑子集；stable 全量；chaos 用确定性轮询而非 sleep |
+| 指标本身不可信 | 指标由 relay 计算；对关键指标加自检（如 task 计数 = ledger 事件计数校验） |
+| 证据造假/过期 | task_id + ledger 区间 + artifact sha 三重校验；过期（>90 天）标记 stale 并在门禁提示 |
+| 测试污染生产数据 | 验收专用项目/临时仓库；grant 限时；验收后清理脚本 |
+| 时长失控（六模块验收） | 每个模块 ≥1 条正向 + 全负向矩阵；完整矩阵按版本 incremental 累加 |
+
+---
+
+## 11. 交付物清单（实现阶段）
+
+```
+scripts/acceptance.mjs            证据骨架生成/校验/汇总
+scripts/chaos.mjs                 进程/网络/配额混沌工具（本地）
+scripts/metrics-check.mjs         指标名与自检
+src/relay/metrics.mjs             新增 M1–M6 计数器/直方图
+src/relay/server.mjs              /metrics 暴露（或复用现有路由）
+scripts/preflight.mjs             新增三项检查（evidence/negative/metrics）
+docs/acceptance/README.md         索引
+docs/acceptance/<version>/…       每个 beta 的证据
+test/acceptance-schema.test.mjs   证据 schema 校验（无证据即失败）
+test/metrics.test.mjs             指标名/单调/自检
+docs/COLLAB/M7-METRICS-ACCEPTANCE.md  本文
+```
+
+## 12. 开放问题（实现前确认）
+
+1. **真机验收执行方式**：人工执行 + 证据上传，还是配置 self-hosted runner 自动跑？前者快、后者可复现。
+2. **SLO 阈值**：任务成功率/事件延迟/上传断点成功率的硬阈值定多少（本稿暂不写数值）？
+3. **证据保留**：90 天过期提示是否合适？历史版本证据是否永久保留？
+4. **混沌工具**：本版本只做本地代理模拟断网，还是也要真机断网（更真实但操作成本高）？
+5. **stable 门槛**：L3 混沌是否强制全过才能 stable（推荐），还是允许豁免清单？
+6. **文档索引机制**：新增 `docs/acceptance/README.md` 作为唯一索引，还是并入现有 claims 的 shipped-documents 列表？

package/docs/COLLAB/TASK-MODEL.md

@@ -0,0 +1,281 @@
+# 任务模型（Task Model）设计规格 — v1.4.1-beta
+
+> 状态：**模型级设计稿**。把 M3（worktree/patch/合并队列/冲突）与既有任务/数据面能力归纳为统一任务模型，冻结任务种类、工作区、制品、分支与合并语义。
+> 版本：`1.4.1-beta.*`；实现按 M3（1.3.4）与 M5 的审查/锁（1.3.6）分步交付，模型一致性验收在 1.4.1-beta 完成。
+> 相关：`docs/COLLAB/M3-GIT-NATIVE-TASKS.md`、`docs/COLLAB/M5-MULTI-CLIENT-PRIMITIVES.md`、`docs/COLLAB/EXECUTION-AUTH-MODEL.md`。
+
+---
+
+## 1. 问题陈述
+
+现状的任务模型只有三个要素：
+
+```
+任务 = argv + 每台机器自己的项目副本 + 事后锚点一致性检查
+```
+
+它隐含三个假设，全部与现实不符：
+
+1. **假设只读**：任务不会改动代码；但真实开发必须改。
+2. **假设幂等**：重试安全；但写文件/提交不幂等，重试会产生两份改动。
+3. **假设结果只是文本**：stdout/stderr；但代码改动需要**可合并的制品**（commit/tree/patch）与**冲突语义**。
+
+后果：多台机器只能"各自跑命令"，无法共同完成一个改动；没有分支/合并/冲突，就没有"联合开发"。
+
+---
+
+## 2. 任务模型总览
+
+```
+Task = 意图 + 输入 + 工作区 + 义务 + 结果 + 证据
+
+意图      kind（exec/worktree/merge/review/maintenance）
+输入      argv、argv 约束、base_commit、project/branch、依赖、授权能力
+工作区    none / copy（旧行为）/ worktree（隔离）
+义务      gates：测试门禁、审查门禁、锁、锚点
+结果      结构化信封：status/outcome + artifacts + workspace 证据 + tests
+证据      ledger 事件 + 内容寻址制品 + 签名/授权来源（provenance）
+```
+
+任务模型与另外两个模型的分工：
+
+| 模型 | 回答的问题 |
+|---|---|
+| 执行授权模型（v1.4.0） | 这台机器**能否执行**这条命令/这次维护 |
+| **任务模型（本文）** | **执行什么、在哪个工作区、产出什么、如何合并** |
+| 协作模型（v1.4.2） | **谁在哪个项目/房间**与谁协作、权限与通知 |
+
+---
+
+## 3. 任务种类（kind）与副作用分类
+
+| kind | 工作区 | 副作用 | 执行者 | 重试语义 |
+|---|---|---|---|---|
+| `exec` | none/copy | 只读（红线保证） | agent | 可自由重试（幂等由只读保证） |
+| `worktree` | 隔离 worktree | 改动代码（制品化） | agent | 新尝试 = 新 worktree（丢弃半成品） |
+| `merge` | 合并专用 worktree | 推进项目 ref | 指定合并器（M2 grant） | 幂等（patch_sha+head 去重，已合并即 no-op） |
+| `review` | 无 | 无代码副作用（结论） | 人/客户端 | 幂等（重复结论拒绝） |
+| `maintenance` | 无 | root 系统动作 | root runner | 幂等（request_id） |
+
+**副作用分类是模型的根**：任务的幂等/重试/隔离策略由副作用类型决定，而不是由调用方口头声明。
+
+---
+
+## 4. 工作区模型
+
+### 4.1 三种工作区
+
+| workspace.kind | 语义 | 隔离 | 用于 |
+|---|---|---|---|
+| `none` | 不提供项目副本（纯命令） | 与机器其他任务共用 | 诊断类 exec |
+| `copy`（兼容默认） | 机器上的现有项目副本 | 无（v1.3.x 行为） | 既有调用方 |
+| `worktree` | 每任务独立 git worktree，起点=base_commit | 强隔离 | 所有会产生代码改动的任务 |
+
+### 4.2 worktree 不变量
+
+1. 起始点严格等于 `base_commit`（不存在则 `BASE_COMMIT_UNKNOWN`）。
+2. 写权限**仅限 worktree 内**；`.git` 管理目录由执行器接管（hooks/config 禁用）。
+3. 任务结束：成功 → 制品化（commit/patch）→ 清理；失败/超时 → 丢弃 worktree。
+4. 并发上限（默认 4/机器）；超限 `WORKTREE_LIMIT`。
+5. 执行前后取 `git status` 快照，作为证据的一部分。
+6. 同一 base 上的两个任务互不可见；合并时才相遇。
+
+### 4.3 为什么不是"各自副本"
+
+`copy` 工作区无法回答"这台机器的改动是相对哪个版本"，也无法隔离并发任务。`worktree` 让改动**总是相对一个明确 base**，从而可传输、可合并、可审计。
+
+---
+
+## 5. 制品模型（Artifact）
+
+制品是任务结果的**一等公民**，内容寻址且不可变：
+
+```json
+{
+  "sha256": "…",
+  "kind": "patch|conflict|diagnostic|report|log|binary",
+  "bytes": 12345,
+  "output_mode": "inline|blob",
+  "label": "patch for 01M6…",
+  "produced_by": { "task_id": "…", "machine_id": "…", "attempt": 1 },
+  "basis": { "base_commit": "…", "head_commit": "…", "tree": "…" },
+  "created_at": "…"
+}
+```
+
+规则：
+
+- **上传完成前不可引用**；引用后内容不可变（sha 就是身份）。
+- `patch` 制品必须携带 `base_commit` 与头部提交信息；合并器只接受"从声明的 base 生成"的 patch，并重新计算 sha 校验。
+- `conflict` 制品是冲突现场（含 conflict markers 的 diff），任何项目成员可下载。
+- 制品可超过内联阈值 → M6 分块/blob 通道；大 patch 不阻塞任务上报。
+- 制品生命周期与项目绑定（M4）；默认保留 30 天，可选永久（发布附件）。
+
+---
+
+## 6. 分支与合并模型
+
+### 6.1 分支
+
+- 项目（M4）拥有一个或多个分支 ref；任务声明 `target_branch`。
+- `base_commit` 必须属于目标分支历史（合并器校验）。
+- 分支 head **只由合并任务推进**；agent 绝不直接写项目 ref。
+- 红线：禁止 force push/改写历史（`FORCE_PUSH_REFUSED`）；head 单调前进。
+
+### 6.2 合并队列
+
+```
+(queue per project+branch)
+  item = {queue_id, patch_sha, base_commit, source_task_id, submitted_by, state}
+  state: queued → claimed → applying → merged | conflict | failed
+```
+
+- 同一队列同一时刻一个合并器（merge-slot lease，M5 的锁是用户级协调，二者互补）。
+- 合并步骤固定：取队首 → 校验 patch_sha/base → `git apply --3way`/`git am` → 门禁 → 推进 head → 事件 → 释放。
+- 合并策略（项目配置）：
+  - `strict`（默认）：base 必须等于当前 head，否则 `BASE_MISMATCH`
+  - `replay`：能干净应用到新 head 则重放，否则冲突
+  - `queue-base`：按队列顺序依次应用（顺序保证，不等价最新 head）
+- 门禁（可组合）：测试门禁（同 patch_sha 测试任务通过）、审查门禁（同 patch_sha 有 approved 审查）、锁门禁（enforced 分支/文件锁）。
+- 幂等：同一 `(patch_sha, target_head)` 已合并 → `already_merged`（no-op）；重放/重试安全。
+
+### 6.3 冲突是一等结果
+
+```json
+{
+  "status": "conflict",
+  "reason_code": "MERGE_CONFLICT",
+  "merge": {
+    "patch_sha": "…", "target_head": "…", "base_commit": "…",
+    "files": ["src/a.mjs"],
+    "hunks": [{"file": "src/a.mjs", "start": 10, "lines": 4, "side": "both"}],
+    "artifact_sha256": "冲突现场（blob）",
+    "next": "由人选择解决者：重新提交到新 base / 手动解决后作为新 patch 入队"
+  }
+}
+```
+
+- 冲突时**绝不推进 head、绝不覆盖任何人的改动**。
+- 不自动重试（防抖动）；解决方式是新 patch 入队。
+- 冲突现场可被审查任务、项目房间、通知引用（M4/M5）。
+
+---
+
+## 7. 结果信封与证据
+
+任务结果统一为结构化信封（向后兼容既有字段）：
+
+```json
+{
+  "task_id": "…", "attempt": 1, "kind": "worktree",
+  "status": "ok|failed|refused|conflict|timeout|expired",
+  "outcome": "ok|no_change|merged|already_merged|…",
+  "reason_code": null,
+  "authorization": { "provenance": "grant|allow-list|maintenance", "capability_id": "…" },
+  "workspace": { "kind": "worktree", "base_commit": "…", "head_commit": "…", "tree": "…", "cleaned": true },
+  "artifacts": [{ "sha256": "…", "kind": "patch", "bytes": 1234, "output_mode": "blob" }],
+  "tests": { "ran": true, "exit_code": 0, "summary": "…" },
+  "evidence": { "status_before": "…", "status_after": "…", "diffstat": {…} },
+  "timings": { "started_at": "…", "ended_at": "…", "duration_ms": 1234 }
+}
+```
+
+规则：
+
+- 结果必须可**仅凭信封**回答：执行了什么（授权来源）、在什么基础上、产出了什么（制品 sha）、有没有门禁。
+- 不引用不存在的制品；上传失败 → `BLOB_UPLOAD_FAILED`（任务失败而不是静默降级）。
+- 结果进 ledger，可重放；`provenance` 用于审计"哪次显式授权"。
+
+---
+
+## 8. 状态机与重试
+
+```
+created → queued(waiting: deps/locks/gates) → offered → running → reporting → terminal
+terminal = done | failed | refused | conflict | timeout | expired | cancelled
+
+merge 任务：queued → claimed → applying → merged | conflict | failed
+retry 规则（按副作用）：
+  exec：可直接重试（只读），attempt += 1
+  worktree：重试 = 新 worktree（从同一 base），旧产物丢弃并记录
+  merge：重试 = 重新入队（幂等）；已合并则 no-op
+  maintenance：重试 = 同 request_id（幂等），已执行返回既有结果
+  任何重试都必须保留 attempt 与去重键，防止双执行
+```
+
+关键不变量：
+
+1. **at-most-once 副作用**：同一 `(task_id, attempt, dedupe_key)` 最多执行一次。
+2. **结果幂等**：relay 对重复结果去重；agent outbox（M6）保证最终投递。
+3. **不悬挂**：租约过期后任务可重派发；策略（halt）决定是否由其他机器接手。
+
+---
+
+## 9. 失败分类（模型级）
+
+```
+输入类：BASE_COMMIT_UNKNOWN、BASE_MISMATCH、PATCH_APPLY_FAILED、ARTIFACT_UNKNOWN
+资源类：WORKTREE_LIMIT、BLOB_QUOTA、OUTBOX_FULL
+门禁类：TESTS_REQUIRED、REVIEW_REQUIRED、LOCK_WAIT_TIMEOUT、PATH_LOCK_CONFLICT
+合并类：MERGE_CONFLICT、FORCE_PUSH_REFUSED、NOT_MERGE_EXECUTOR、MERGE_ABORTED
+授权类：RED_LINE_VIOLATION、NOT_AUTHORIZED、GRANT_*、MAINTENANCE_*
+传输类：BLOB_INCOMPLETE、BLOB_SHA_MISMATCH、SESSION_NOT_FOUND
+```
+
+每类都必须有负向测试（M7 的 negative matrix）。
+
+---
+
+## 10. 兼容与迁移
+
+- 新字段全部可选；`kind` 缺省 = `exec`，`workspace.kind` 缺省 = `copy` → 既有调用方行为不变。
+- 旧 relay 忽略新字段；旧 agent 按旧逻辑执行（可能拒绝或只读）。
+- 旧任务（无 project_id）惰性归入 default 项目（M4）；不重写 ledger。
+- 迁移路径：`exec/copy` → 逐步把写任务切到 `worktree`；合并队列按项目启用（默认不启用，显式开启）。
+
+---
+
+## 11. 验收（模型一致性）
+
+### 正向（真实任务证据）
+
+1. **联合改动**：两机各自 worktree 任务（不同文件）→ 两个 patch 入队 → 合并器依次合并 → 项目 head 含两者改动，测试通过，两条 ref.updated 事件。
+2. **冲突**：两机改同一处 → 第二个 item 返回结构化 `MERGE_CONFLICT`（文件/hunk/现场 blob），head 不变。
+3. **base 前进**：strict 下返回 `BASE_MISMATCH`；replay 下干净应用则自动合并。
+4. **门禁**：测试/审查/锁门禁分别挡住合并，满足后续行。
+5. **幂等**：同 patch 重复入队 → `already_merged`；worktree 任务重试不产生两份改动。
+6. **结果证据**：每个任务信封能独立回答"授权来源/base/制品/门禁"。
+
+### 负向（自动化矩阵）
+
+```
+非 worktree 产出的 patch / 篡改 sha / 写 .git / 直接改项目 ref / force push /
+merge 中断后锁恢复 / worktree 超限 / 冲突被误判为成功 / 缺门禁仍合并 /
+重试双执行 / 结果引用不存在的 blob → 全部对应错误码且 ref 不变
+```
+
+---
+
+## 12. 与版本/模块的映射
+
+```
+1.3.4-beta  M3 实现：worktree/patch/合并队列/冲突（本章 §4–§7 的落地）
+1.3.6-beta  M5 实现：锁与审查任务（本章门禁部分）
+1.4.1-beta  模型一致性验收：统一 kind/结果信封/幂等语义/失败分类
+共享模块：
+  src/relay/task-model.mjs      任务种类与状态机、副作用分类
+  src/relay/merge-queue.mjs     队列/merge-slot/门禁/幂等
+  src/relay/project-ref.mjs     分支 head 与单调推进
+  src/agent/worktree.mjs        工作区生命周期（M3）
+  src/agent/patch-artifact.mjs  制品生成/上传/证据
+```
+
+## 13. 开放问题（实现前确认）
+
+1. **写任务的默认 kind**：显式 `worktree` 才允许写（推荐），还是 copy 也允许写（兼容但危险）？
+2. **仓库来源**：项目 origin 指向 GitHub 私仓还是 relay 本机 bare？合并在哪一侧执行？
+3. **合并策略默认**：strict（推荐）还是 replay？
+4. **门禁默认**：测试/审查默认关闭、按项目开启（推荐）？
+5. **非 git 项目**：是否支持"无 git 的 worktree"（文件级快照/补丁）还是只支持 git？
+6. **Windows**：大小写不敏感与 symlink 限制如何表达（限制 patch 内容/仅告警）？
+7. **制品保留**：30 天默认够不够？发布附件是否永久保留？