# dsh-dag-orchestrator — 断点续跑的多任务并行 DAG 编排插件 · 架构设计

> 状态：设计定稿（2026-08-16）。实现前配合 `docs/TASKS.md` 阅读。
> 移植源：task-weaver `packages/scheduler/`（15 文件 ~6.1k 行，逐文件实读）+ `packages/application/src/services/recovery-service.ts`（1269 行崩溃对账）。
> 范式样板：`dsh-plugin-subagents`（apply() 模式、zod strict、一模块一工具、node:test 纪律）与 `dsh-worktrees`（引擎/工具分离、构造注入、原子写纪律）。
> 前期基线：`dsh-plugin-subagents/docs/task-weaver-integration-analysis.md` §3 处置清单 2、§4 DSH 落地硬约束（C4/C6/C7 全部适用）。
> 本文所有「直搬/改写/裁掉」论断均标注 task-weaver 源文件 + 函数名 + 行号（证据式设计）。

---

## 0. 已拍板决策（承自任务书与上游裁决，不再作为开放问题）

| # | 决策 | 来源 |
|---|---|---|
| D1 | 插件名 `dsh-dag-orchestrator`；**随宿主生死**：自带持久化 + 重启对账，DSH 重开后断点续跑；**不做独立进程** | 任务书 + 分析 §0 |
| D2 | **不拆 dsh-approvals**：审批作为 DAG 内部 task kind 吸收（照 task-weaver `kind: approval` 建模，`task-executors.ts` L191-256） | 分析 §0 用户裁决 |
| D3 | 优先级低于 dsh-worktrees：**复用其 §10 组合缝**（merge-queue 引擎单例、origin/correlationId、DrainOutcome 五态），不发明重复接口 | 任务书 |
| D4 | 执行层**换绑 DSH subagent 工具族**：不再用 task-weaver 的 adapter/CLI 进程模型 | 任务书核心 |
| D5 | Plain JS ESM、零新增运行时依赖（zod 除外，同家族 `zod@^3.23.0`；**JSON-only spec，不引 yaml**，§7.4 论证） | 任务书硬约束 |
| D6 | 2959 行 scheduler-loop.ts **不整体搬**：吸收设计重写（tick 骨架 + 状态机 + CAS 语义保留，执行器/watchdog/budget/circuit-breaker/review 裁掉） | 分析 §3.2 MVP 克制 |

## 0.1 本设计新定案的决策（原开放问题，已在本文论证）

| # | 决策 | 论证位置 |
|---|---|---|
| D7 | 执行绑定 = **`ctx.subagents.start(name, SubagentStartRequest)` 程序化一次性路径**（native in-process 为主档）；bridge 后端 MVP 走 stock 一次性路径（**不带 settings**），settings 级 bridge 派发列为开放问题 O2 | §4.2/§4.3 |
| D8 | 节点跟踪 = **engine 持有 `SubagentRun.result` promise map + `subagent/end` 事件做观测 + tick 收割**（非轮询进度、非纯事件驱动） | §4.4 |
| D9 | 持久化 = **node:sqlite 单库（WAL + 0600）**：投影与事件**同事务**是本插件的存在理由，JSONL 双文件方案破坏该不变量 → 不采用；JSONL 仅作导出/审计的后续可选项 | §6.1 |
| D10 | `dag_tick` = **有界多轮 reconcile**（`maxRounds` 内循环单轮 + 零进展时等待 in-flight settle，**等待预算全调用累计 ≤ settle_ms**、非每轮重置，连续 2 轮零 settle 即退），模型反复调用即"驱动循环"（对照 task-weaver `SchedulerDriver.driveToCompletion` 三停条件的 DSH 等价物） | §5 |
| D11 | 资源准入 = **进程内内存信号量**（slots / shared_key 会话键），**不持久化租约**——崩溃后一切 in-flight 判 orphaned，持久租约无消费者（§6.4 论证） | §5.4 |
| D12 | 事件 **hash 链保留**（sha256 链式，加载时校验，失配拒启）——便宜且是「投影+事件同事务」的可审计伴生物 | §6.3 |
| D13 | 工具面 5 件：`dag_plan / dag_status / dag_tick / dag_control / dag_approve` | §8 |

---

## 1. 目标与非目标

### 1.1 目标（MVP 全量 = M1+M2+M3 三个里程碑）

1. **静态 DAG 编排**：JSON spec（`dag_plan` 提交）→ 校验（strict、无环、引用完整）→ 持久化 → 断点续跑。
2. **并行 agent 任务**：DAG 节点 = 一次 subagent 委派（native 后端，per-call model/persona/toolFilter/cwd）；`limits.maxRunningAgents` 并发上限；critical-path 优先级调度。
3. **依赖与条件**：`dependsOn: [{taskId, condition: succeeded|completed}]`（语义逐字照搬 task-weaver `Dependency`，`workflow-spec.md` L217-228：`completed` = succeeded|failed|cancelled，**不含 blocked**）。
4. **重试**：RetryPolicy（maxAttempts/backoffMs/maxBackoffMs/retryOn）——`shouldRetry`（scheduler-loop.ts L2295-2329）语义直搬：指数退避 + 抖动、retryOn 过滤、`attempt.retry_scheduled` 事件。
5. **失败传播**：`propagateDownstream`（readiness.ts L165-203）语义直搬：上游 failed + `block_downstream` → 下游 `blocked(upstream_failed)`。
6. **崩溃对账**：DSH 重启 → `apply()` 内、工具注册**之前**（分析 §4-C4）：加载 → hash 链校验 → in-flight attempt 分类（照 recovery-service.ts 四分类 + no-process，映射到 subagent 会话语境，§12）。
7. **审批节点**：`kind: approval` 内置（照 `runApprovalTask` L191-256：request → park `blocked(approval_pending)` → `dag_approve` 决策 → 下轮 reconcile 提升 succeeded/failed）。**不是独立审批系统**——是 DAG 内的一个节点类型。
8. **worktrees 组合**（M3）：`kind: merge` 节点 → dsh-worktrees merge-queue 引擎单例（其 DESIGN §10 组合缝）；写任务的 worktree 由 **DAG 编排在派发时创建**（origin:'dag' + correlationId=attemptId，§11）。
9. **状态可观测**：`dag_status` 投影查询（run/task/attempt 三级 + 事件尾窗）。

### 1.2 非目标（scope 边界）

- **不做常驻调度进程 / 独立 server**（D1；分析 §3「不整合」项）。宿主进程即调度进程，泵 = 工具调用。
- **不做 UI**（MVP 纯 tool；分析 §4「UI 无官方侧边栏 slot」的家族成本另议）。
- **不迁移**：budget/watchdog/circuit-breaker/adapter 健康度/review 门/ExecutionGrant/PID marker/ProcessRecord（§9 迁移表逐条给理由）。
- **不做 verify 命令执行器**：task-weaver 的 `verify` kind 由 VerifyService 跑 argv 命令；本插件 M3 把验证建为 **outputSchema 契约门**（agent 任务产出 `{status}` 结构化结果 + 直搬 `evaluateVerifyGate` 的receipt 判定形状），不新增插件自有的子进程执行面（§7.3）。
- **不做 artifact 存储体系**：MVP 的「产物」= 每任务至多一个 outputSchema 结构化结果（`SubagentResult.structured`），存 outputs 表；无 content-addressed storage、无跨 run 查询。
- **不做跨进程/多 dsh 实例并发**：单宿主进程单写者（O5 与 worktrees 同立场；WAL 防损坏、不防并发写语义）。
- **不做 bridge 后端的 settings 级派发**（model/permissionMode/reasoningEffort）：stock 一次性路径证明不带 settings（§4.3 实证），列为 O2 开放问题；M1 结构性只开 native。
- **不接管官方工具名**：全部 `dag_*` 新名字，全局层天然可见（worktrees DESIGN §1.2 同一机制结论）。

---

## 2. 现状与依赖（证据基线）

### 2.1 移植源：task-weaver `packages/scheduler/`（逐文件实读，行数为实读值）

| 文件 | 行数 | 职责 | 关键接口（证据） | 处置（§9 详表） |
|---|---|---|---|---|
| `scheduler-loop.ts` | 2959 | 单轮 reconcile 循环 | `tick(runId)` L552-690（14 步序）；`claimSpawnDrainCommit` L897-1094；`claimTask` L1943-2056（ready→queued→running 双 CAS + Attempt 内嵌 claim/lease，同事务）；`shouldRetry` L2295-2329；`emitTaskEvent/emitAttemptEvent` L2788-2840；`awaitOutcomeBounded` L1755-1815 | **吸收重写** |
| `terminal-commit.ts` | 262 | 每 Attempt 独立终态提交 | `commitTerminalAndReleaseStandalone` L80-261：一个事务内 commitTerminal(校验 owner+lease) → 事件 → task CAS；租约释放在事务**外**；retry 分支先提交 Attempt 终态再 CAS task→retry_wait（Issue 5 顺序论证 L106-125） | **语义直搬**（持久层换 sqlite） |
| `readiness.ts` | 231 | ready 提升 / 失败传播 / 队列构建 | `promoteReady` L71-159（evaluateReady → 单事务 CAS pending/retry_wait/blocked→ready/blocked + 事件）；`propagateDownstream` L165-203；`buildQueue` L209-231 | **直搬改造** |
| `ready-evaluator.ts` | 444 | 纯函数 ready/blocked 判定 | `evaluateReady` L272-443（纯函数，无 DB I/O）；`upstreamSatisfies` L206-225（in-progress/completed 集合判定）；`isReadySource` L239-263（pending 恒评估；retry_wait 到期评估；blocked 重评但 approval_pending 等 park 排除）；`evaluateGate` L97-122（五算子有限布尔检查） | **直搬收窄** |
| `bounded-queue.ts` | 150 | 有界 ready 队列 | `BoundedQueue` + `compareQueueEntries` L48-69（5 级确定性优先级：humanUnblocked → criticalPathDepth 降 → priority 降 → readyAt 升 → taskId 字典序）；`tryEnqueue` 满不抛（下轮重评） | **直搬** |
| `critical-path.ts` | 33 | 关键路径深度 | `criticalPathDepth` L10-33（memo DFS 纯函数） | **直搬** |
| `verify-gate.ts` | 119 | 验证完成门 | `evaluateVerifyGate` L79-115（无 verify 声明 → `evidence:'none_declared'`；有声明但 receipt 缺失/未过 → 合成 permanent 失败）；`findVerifyReceipt` L45-64 | **M3 直搬改造**（receipt 源换 outputs 表） |
| `resource-admission.ts` | 250 | 多维资源租约 | `SqliteResourceAdmission.tryAcquire` L159-196（稳定排序 + all-or-nothing + conflictKey）；`ResourceLeaseStore` 端口 L93-110 | **裁掉**（D11：内存信号量替代） |
| `process-slots.ts` | 71 | N 路进程槽键 | `buildProcessSlotKeys` L29-40（`global:process:slot:0..N-1`）；`tryAcquireProcessSlot` L53-71（N 次单键尝试取任一空槽） | **语义直搬**（键改内存 Map） |
| `parking-policy.ts` | 437 | 三种 park | `parkForUnavailableAdapter` / `parkForReview` / `reconcileReviewPending`（commit attempt failed → CAS task blocked → 事件，同事务；租约外释） | **裁掉**（adapter/review 不迁移；approval park 语义并入 executor） |
| `capacity-governor.ts` | 103 | 预算软节流 | `effectiveMaxRunningProcesses` L56-61 | **裁掉**（budget 不迁移） |
| `task-executors.ts` | 322 | merge/verify/approval 执行器 | `runApprovalTask` L191-256（approved→成功；rejected→`policy_denied`；否则 request + park approval_pending）；`runMergeTask` L67-185（enqueue 每个 input → applyNext 循环 → conflicted/failed 映射） | **approval 直搬语义 / merge M3 改造 / verify 裁掉** |
| `scheduler-driver.ts` | 553 | 驱动循环 + Run 终态投影 | `driveToCompletion` L243-381（三停条件：Run 终态 / 零进展且无 pendingWork 或 waitingExternal / 迭代上限）；`finalizeRunIfDone` L401-489（聚合任务终态 → run.succeeded/failed/cancelled，同事务）；`isSoftBlocked` L529-549 | **语义直搬**（折叠进 dag_tick） |
| `types.ts` | 62 | 冻结类型 | `BlockedReason` / `ReadyEvaluation` / `TaskGraphSnapshot` / `TaskGraphTaskView` | **直搬** |
| `readiness.ts` 之外另注：`index.ts`(75) | 包出口 | —— | **裁掉**（插件入口是 apply()） |

**调度循环单轮 14 步序**（scheduler-loop.ts 模块头 L4-35 + tick 实现，本设计 §5 的对照基准）：
1. reconcile 过期租约 → 2.（review reconcile）→ 3. promoteReady → admission-closed 门 → 4. buildQueue（BoundedQueue）→ 5-6. **并发** claimSpawnDrainCommit（每 drive 独立取槽 + 独立 CAS claim + 独立终态事务；`Promise.allSettled` 仅并发屏障，**绝不批量 sibling 终态**——不可协商不变量 #1，L583-600）→ 7. spawn（事务外）→ 8. drain 事件流 → 9. outputs/verify 门 → 10. 终态 CAS（单事务）→ 11. 释放资源（事务外）→ 12. propagateDownstream → 13. checkBudget → 14. drainToPaused。

**三硬不变量**（L20-35 原文照搬，全部继承）：
- **#1** 禁止 Promise.all 后批量 sibling 终态；每 Attempt 独立 CAS 提交。
- **#3** ready 评估 + 状态更新同事务；spawn/I/O 在事务外。
- **#6** 每次状态变更在**同一事务**内发出持久 Event。

### 2.2 DSH 宿主面（实读 `.d.ts` / 实现核实，DSH 0.1.0-rc.6）

- **程序化 subagent 委派（执行绑定的地基）**：`ctx.subagents.start(name, request): Promise<SubagentRun>`（`dsh-subagent/lib/types/index.d.ts` L259）——**纯代码可调，不经模型工具调用**。`SubagentStartRequest`（types.d.ts L93-140）：`{ label?, prompt: ContentBlock[], parent: Agent, signal: AbortSignal, agentOptions?: AgentOptions, outputSchema?, maxDepth?, toolFilter?, persona? }`。
- **`AgentOptions` 的真实形状**（`dsh-agent/lib/types/runtime-types.d.ts` L21-28，实读）：`{ provider?: string; model?: string; maxTokens?: number }` —— **携带 LLM 路由，不携带 permissionMode/reasoningEffort**（那两个是产品 CLI 概念，走 bridge settings）。
- **`SubagentRun`**（types.d.ts L233-259）：`{ id: SessionId, localAgent?, result: Promise<SubagentResult>, dispose(): Promise<void> }`；`SubagentResult = { output: ContentBlock[], structured?: unknown, stopReason: 'completed'|'aborted'|'error'|'max-tokens'|'refusal' }`（L202-230）。**result 不因子级失败 reject**（infrastructure fault 才 reject）——engine 的收割契约。
- **bridge provider 一次性路径不带 settings（实证）**：dsh-plugin-subagents `lib/drivers/bridge.js` L315-336——`start(request)` = `bridge.create(cwd)` + `bridge.submit(remote, task, signal, cwd)`，注释明示「settings 不经此路：harness 的 SubagentStartRequest 无 bridge 设置概念」；settings 只在 relay/continuable 路径随 binding 补写（L418-419）。⇒ 见 §4.3 与 O2。
- **事件总线**：cordis `EventsService`；`subagent/start` / `subagent/end`（`SubagentRunInfo` / `SubagentRunEndInfo`，types.d.ts L26-66）**按委派父 scope 过滤分发**——engine 作为派发者天然在自己的 scope 收到配对事件（观测通道，§4.4）。
- **provider 注册面**：`ctx.subagents.registerProvider(provider): () => void`（effect-scoped，index.d.ts L237-243）、`getProvider(name)`、`list()`——O2 的 DAG 自有 wrapper provider 路径存在该公开缝。
- **工具注册**：`ctx.tools.register(defineTool({...}))`；`ParameterSchemaSpec` 每属性 `{type, required?, description?, enum?, items?}`；输出 `ValueSchemaSpec`（oneOf 分支需 `additionalProperties: false` + 逐属性 required）——`dsh-tools/lib/types/schema.d.ts` L55-94（worktrees DESIGN §2.2 已核，此处沿用）。工具返回经无损 JSON 快照校验（undefined 值键整体被拒 → 一切返回条件展开构造）。
- **执行上下文**：`execute(args, exec)`；`exec.agent` = 调用方 live Agent（派发 parent 的来源，§4.2）；`exec.signal` = 工具调用取消信号（只门 tick 的同步段，**不**接进 attempt 生命周期——engine 自持 AbortController）。
- **node:sqlite 先例**：`dsh-session-query-sqlite/lib/index.js` L49-82——`await import("node:sqlite")` 动态导入 `DatabaseSync`；`PRAGMA journal_mode=WAL`；`wx` 独占创建 0600；`application_id`/`user_version` 所有权守卫；进程内串行化代替文件锁。本插件同款纪律（§6）。
- **apply() 返回值必须 undefined**（Cordis 非 disposable 校验 TypeError，分析 §4）；`ctx.effect(() => disposer)` 清理模型。
- **C6 peer 双实例陷阱**：`@deepseek-ai/*` 必须 peerDependencies + symlink 到 live harness 根（subagents `patches/install.sh` A 段模式）；apply() 开头 `assertSingleDshToolsInstance`（Symbol 自检）。本插件 peer 面最小化：`cordis` + `dsh-tools` + `dsh-subagent`（纯函数白名单导入，§4.2）。
- **ctx.jobs**：插件可注册自有 job kind（JobKindMap 可合并扩展），但 `JobRegistry.start(spec)` 需要附着 controller（dsh-tool-jobs 提供）——**不采用**：tick 泵 = 工具调用 + 可选 `ctx.effect(setInterval)` 自 Timer（§5.5 论证）。

### 2.3 组合对象

- **dsh-plugin-subagents 工具面**（引用其 DESIGN §5.3 归一 schema）：`subagent(description, prompt, backend?, role?, model?, persona?, toolFilter?, cwd?, permission_mode?, run_in_background?)`——本插件的 spec 字段命名与之对齐（model/persona/toolFilter/cwd 同名同义），模型心智零迁移。
- **dsh-worktrees 组合缝**（引用其 DESIGN §10）：① `createMergeQueue({git, store, config})` 引擎单例导出，`enqueue(params)` / `drain(repoKey, branch): Promise<DrainOutcome>` 是稳定 API；② merge job 记录 `origin: 'dag'` + correlationId；③ DrainOutcome 五态 succeeded/conflicted/queued/failed/no_changes。**明确禁止**：DAG 侧自建第二实例指向同一 state.json（双写者破坏其单写者不变量）。

---

## 3. 总体架构

```
┌────────────────────────────────────────────────────────────────────────┐
│ DSH 宿主（Cordis）                                                      │
│                                                                        │
│  apply(ctx, config)  ← lib/index.js                                    │
│   ├─ validateConfig（zod strict，lib/config.js）                        │
│   ├─ DagStore.open()（node:sqlite WAL 0600；hash 链校验）               │
│   ├─ reconcile()（崩溃对账：§12 —— 先于工具注册，C4）                   │
│   ├─ ctx.effect：subagent/end 观测订阅 + 可选 autoTick Timer（默认关）  │
│   └─ 注册 5 工具（lib/tools/*.js → ctx.tools.register(defineTool)）     │
│                                                                        │
│  工具层（模型可见）                引擎层（工具共享，apply() 单例闭包）   │
│  ┌───────────────┐                 ┌────────────────────────────────┐  │
│  │ dag_plan      │──submit/validate▶│ DagEngine                      │  │
│  │ dag_status    │──project────────▶│  tick(): §5 单轮×maxRounds     │  │
│  │ dag_tick      │──pump──────────▶│   ├─ reconcileApprovals        │  │
│  │ dag_control   │──intent────────▶│   ├─ promoteReady（直搬改造）   │  │
│  │ dag_approve   │──decision──────▶│   ├─ propagateDownstream       │  │
│  └───────────────┘                 │   ├─ dispatch（ExecutorPort）   │  │
│                                    │   ├─ harvestSettled             │  │
│                                    │   └─ finalizeRunIfDone          │  │
│                                    ├────────────────────────────────┤  │
│                                    │ Executor（native 绑定，§4）      │  │
│                                    │  ctx.subagents.start(...)       │  │
│                                    │  inFlight: Map<attemptId,       │  │
│                                    │    {run, controller, timer}>    │  │
│                                    ├────────────────────────────────┤  │
│                                    │ Admission（内存信号量，D11）     │  │
│                                    │  slots / sessionKeys            │  │
│                                    ├────────────────────────────────┤  │
│                                    │ DagStore（sqlite 唯一持久化出口） │  │
│                                    │  tx(): 投影+事件+hash 同事务     │  │
│                                    └────────────────────────────────┘  │
│  正交组合（无代码耦合，M3）：                                             │
│   merge 节点 → dsh-worktrees merge-queue 引擎单例（其 §10 缝）           │
│   写任务 worktree → worktree 引擎 createWorktree(origin:'dag')           │
│   任务 subagent 的 cwd ← worktree path（subagents per-call cwd）         │
└────────────────────────────────────────────────────────────────────────┘
```

分层纪律（沿家族范式）：

- **工具层只做**：参数 schema、调引擎、把结果条件展开成无损 JSON。不含状态写、不含 subagent 调用。
- **引擎层**：DagStore 是唯一持久化出口；`tx(fn)` 内投影变更 + 事件插入 + hash 推进**原子**；一切 subagent 派发/await/abort 在事务**外**（不变量 #3）。Executor 与 Admission 以构造注入（`{ store, ctx, execAgentProvider }`），不 import 宿主服务——与 worktrees §10 同款可测缝。
- **单实例状态**：DagEngine/inFlight Map/信号量只存在于 `apply()` 建立的唯一闭包（subagents 红线 10 同款）。
- **apply() 返回 undefined**；teardown 经 `ctx.effect`（清 Timer、dispose 全部 in-flight run、关库）。

---

## 4. 执行层换绑（核心问题 1）

### 4.1 换绑总则

task-weaver 的执行单元 = `adapter.start(AgentRunRequest)` spawn 一个 CLI 进程（scheduler-loop.ts L1388 `agentProcess = await adapter.start(req)`），进程事件流 drain 进 `agent.*` 持久事件（`drainEvents` L2097-2140），退出经 `awaitOutcomeBounded`（L1755-1815）得 `AgentExitOutcome { exit, failure }`。

DSH 形态换绑映射：

| task-weaver 概念 | DSH 等价物 | 证据/理由 |
|---|---|---|
| `adapter.start(req)` | `ctx.subagents.start(provider, SubagentStartRequest)` | §2.2 程序化一次性路径 |
| `AgentProcess.done` + 事件流 | `SubagentRun.result: Promise<SubagentResult>`（无中间事件流可订；观测走 `subagent/end` 事件） | types.d.ts L233-259 |
| `AgentExitOutcome.failure`（7 类 failureType） | `SubagentResult.stopReason`（5 值）+ infrastructure reject | 映射表 §4.5 |
| `AgentProfile`（model/promptPrefix/skills/permissions） | `SubagentStartRequest.{agentOptions, persona, toolFilter, maxDepth}` | §2.2 AgentOptions 实证 |
| `cwd`（workspace handle path） | `request` 透传 `cwd`（需 subagents cwd 补丁）+ worktrees worktree path | subagents DESIGN §2.1 补丁证据链 |
| ProcessRecord / PID marker / heartbeat | **无对应物也不需要**：进程随宿主生死（D1），崩溃恢复按「宿主退出 ⇒ in-flight 全部 orphaned」处理（§12） | 分析 §4-C4 |
| `runtimeTimeoutMs` 硬超时 | engine 自持 `AbortController` + `setTimeout` → `controller.abort()` → result 以 `aborted` settle | §4.5 |

### 4.2 Native 绑定全链路（M1 主档）

```
dispatch(task, attempt, exec):
  1. prompt 组装（§7.4：spec.prompt + 上游 outputs 内联头 + 边界分隔符）
  2. request = {
       label: `${run.name}/${task.id}#${attempt.ordinal}`,
       prompt: [{type:'text', text: prompt}],
       parent: exec.agent,                        // 当前 tick 调用方 live Agent（§4.4 归属论证）
       signal: engine.controllers.get(attemptId).signal,   // engine 自持，非 exec.signal
       agentOptions: {provider: task.provider?, model: task.model?, maxTokens: task.maxTokens?},
       persona: task.persona?,                     // 含 @preset: 引用（subagents 同语义）
       toolFilter: task.toolFilter ?? DEFAULT_TASK_FILTER,  // deny dag_* + subagent（红线 5）
       maxDepth: task.maxDepth ?? 1,
       ...(task.output ? {outputSchema: task.output.schema} : {}),
       ...(task.cwd ? {cwd: task.cwd} : {}),       // 需 subagents cwd 补丁就位（§4.6）
     }
  3. run = await ctxSubagents.start(backend, request)   // backend = task.backend ?? 'spawn'；'native' 别名映射为 'spawn'（harness 只注册 spawn/fork 两个 provider 名，0.1.0 后审计 P2）
     └─ 失败（reject）：终态提交 failureType 'transient' code 'dag.dispatch_failed'（retryOn 匹配可重试）
  4. inFlight.set(attemptId, { run, controller, timeoutTimer })
  5. 派发即返回（不 await result）——收割归 tick（§4.4）
```

**`DEFAULT_TASK_FILTER = {deny: ['dag_plan','dag_status','dag_tick','dag_control','dag_approve','subagent','subagent_fork']}`**：DAG 任务子代理**默认**无 DAG 控制面、无再委派（结构性防注入，红线 5；spec 可显式放开 `delegation: true` → 从 deny 移除 subagent 两项）。注意 dsh 原生 toolFilter 对未知名 loud 校验（`tools.restrict()` throw）。（0.1.0 后审计 P1 修订：该 throw 对**任何**未注册名生效、发生在子代理创建窗口内 → 全部派发 transient 重试空烧。地板现按两层裁剪——① apply 时按 register 开关裁掉未注册的 `dag_*` 条目；② 派发时若拿到宿主 ToolRuntime face（`ctx.tools.view(execAgent).restrictableNames`，泵者视图 ⊇ 子代理视图），把 allow/deny 与实际可 restrict 名集求交。裁剪只删**本部署不存在**的名字（deny 不存在的工具本就无意义），已注册 `dag_*` 的地板语义不变；测试用 fake ctx 无 face 时退化为不裁剪。）

**深度治理**：DAG 派发的子代理 depth = parent depth + 1；`assertSubagentMaxDepth`（`@deepseek-ai/dsh-subagent` 纯函数白名单成员，subagents DESIGN §6.4.4）在 dispatch 前断言，防 DAG 层叠出无限委派树。这是本插件对 `@deepseek-ai/dsh-subagent` 的**唯一**直接 import（白名单纪律照搬 subagents 红线 12，lint 强制）。

### 4.3 Bridge 绑定：MVP 的事实边界与三条出路

**实证**（§2.2）：stock bridge provider 的一次性 `start()` = create + submit，**不携带 settings**（model/permissionMode/reasoningEffort 只随 relay/continuable binding 补写）。因此：

| 选项 | 内容 | 判定 |
|---|---|---|
| A（M1 采用） | **spec 不开 bridge 后端**：`task.backend` 仅接受 `native`/`spawn`/`fork`；`permission_mode`/`reasoning_effort` 字段出现即 loud error（对照 subagents 能力矩阵「不支持参数不静默忽略」红线 8） | 结构性诚实，零新面 |
| B（O2 后备） | DAG 经 `ctx.subagents.registerProvider()` 注册自有 wrapper provider（如 `dag:codex:ro`），闭包捕获每 (provider, settings) 组合的 bridge——需要 subagents 插件**导出 bridge 工厂**或引擎级 dispatch API（当前未导出；深路径 import 私有模块脆弱） | 列开放问题 O2：建议 subagents 增加 `dispatchAgentTask({backend, settings, ...})` 引擎导出（与 worktrees `createMergeQueue` 同款 §10 缝） |
| C（否决） | DAG 派一个 relay 型 continuable 子代理再驱动其调 `subagent_submit` | 需要 model 驱动的中继回合，DAG 执行器是代码不是模型——引入「伪 relay」复杂度且绕开天花板校验，否决 |

### 4.4 节点状态机如何跟踪 subagent（选型论证，核心）

三个候选：

1. **纯事件驱动**（只订 `subagent/end`）：事件按**委派父 scope** 过滤分发（§2.2）——engine 是派发者故能收到；但事件是「通知」不是「结果载体」（payload 仅 stopReason + lastAssistantMessage，无 `structured`），且事件回调里做终态提交会把引擎状态机耦合进事件时序（丢事件 = 永不终态）。
2. **轮询进度**（每 tick `subagent_progress`）：DSH 有此工具但它是模型工具，代码侧等价物要折叠 session 日志——重且慢；进度≠终态。
3. **engine 持有 promise + 事件观测 + tick 收割（D8，选定）**：`inFlight` Map 持 `{run, controller, timer}`；`run.result` 是**权威终态载体**（含 output/structured/stopReason）；`harvestSettled()` 每 tick 用同步检查 `promiseState`（手写 `promiseState` 工具：`Promise.withResolvers` 不用，Node≥22 家族纪律照 worktrees §2.2——手写 reflected-promise 包装器 `reflect(p)` 存 `{status:'pending'|'fulfilled'}`）收割已 settle 的 attempt 并走终态提交；`subagent/end` 订阅仅做两件事：惰性触发一次**轻量收割**（event → engine.harvestSafely()，幂等，promise 为主体）+ 日志观测。事件丢失的兜底 = 下一次 tick 的收割（tick 是幂等泵，天然自愈）。

**结论**：promise 是事实源、事件是加速器、tick 是兜底。三者都到 → 无单点。**不采用**纯事件或纯轮询。

**parent 归属规则**：dispatch 的 `parent` = **当前 tick 调用方的 `exec.agent`**（不是 run 创建者）。理由：DSH 无「DAG 会话」实体，派发必须挂在 live Agent 上；子代理的 workspace/depth 由 parent 派生，而 DAG 任务 workspace 由 per-task cwd 显式给定，parent 仅承载 depth/lineage —— 挂当前泵者语义正确且实现无死角。跨会话续跑（A 会话 plan、B 会话 tick）因此天然成立。wrinkle（记录于 README）：子代理 session 的 parentSession 记为最后一位泵者。

### 4.5 结果回填与失败映射

```
harvestOne(attemptId):
  reflected = inFlight.get(attemptId); clearTimeout(timer)
  try result = await reflected.promise catch e → infraReject 路径
  映射（对照 task-weaver AgentFailure 形状，scheduler-loop 各 commit 点的 failureType 取值）:
    stopReason 'completed'
      + task.output 声明且 result.structured 缺失 → permanent 'dag.missing_output'
        （对照 shapeOutcome 的 declared-outputs 门 scheduler-loop.ts L1722-1738 + verify-gate L102-114 哲学）
      + outputSchema 校验失败（structured 存在但结构不符）→ permanent 'dag.output_schema_violated'
      否则 → succeeded（outputs 表落 value_json；attempt.result_json 存结构化/文本摘要）
    'error'   → failureType 'transient'（LLM/传输类）code 'dag.agent_error' → shouldRetry 按 retryOn 判定
    'aborted' → 超时引发（timer 先触发）→ failureType 'timeout' code 'dag.attempt_timeout'
                （retryOn 键映射照 failureTypeToPolicyKey L2909-2913：timeout → transient_network 键）
                非超时 abort（dag_control stop / 宿主 teardown）→ 'aborted' 不可重试，task 走 cancelled 语义
    'max-tokens' → permanent 'dag.max_tokens'（不可重试：同 prompt 重试大概率同样爆）
    'refusal'    → permanent 'dag.refusal'
    infraReject（result promise reject）→ 'internal' 'dag.infra'（不可重试，loud）
  commitTerminal(attempt, target, failure)   // §5.3 事务形状
```

**输出存储**：`outputs(run_id, task_id, name, value_json, produced_by_attempt)`——`SubagentResult.structured` 是单一 JSON 值；spec 的 output.name 是其在 DAG 命名空间的键。下游 `inputs: ['task://<taskId>/<name>']` 解析到此表（MVP DataRef 语法，§7.2；不用 task-weaver 的 `artifact://` 防与 artifact 体系混淆）。

### 4.6 cwd 与 worktree（M3 深组合预埋）

- M1：`task.cwd` 可选；缺省 = run 创建时的 `baseCwd`（dag_plan 的 `exec.agent.session.header.cwd`）。校验：绝对路径 + realpath 后落在（workspaceRegistry ∪ baseCwd 子树 ∪ config.allowedRoots）——**复用 worktrees repo-gate 的判定形态**（其 DESIGN §5.2.0），本地实现不 import 其模块（独立包，不引依赖）。
- M3：`task.worktree: {task: <slug>, baseRef?}` 声明式开关——dispatch **前**经 worktrees 引擎单例 `createWorktree({task, repoRoot, baseRef, origin:'dag', correlationId: attemptId})` 取 path 作为 cwd；attempt 终态后 worktree 生命周期仍归 worktrees 工具（DAG 不接管 cleanup，worktrees §10 明确不做生命周期接管）。缺 worktrees 引擎 → loud `dag.worktrees_unavailable`。

---

## 5. tick 模型（核心问题 2）

### 5.1 单轮 reconcile（oneRound）—— 照 scheduler-loop 14 步序收窄

| # | 步骤 | 源对照 | DSH 落地 |
|---|---|---|---|
| 1 | reconcile 过期租约 | `reconcileExpired` L833-851 | **裁**（D11：无持久租约；in-flight 超时由 engine timer 管） |
| 2 | 审批 reconcile | `reconcileReviewPending` 的 approval 近亲：approvals 表查已决 → CAS 提升 | `reconcileApprovals`：approved → blocked→succeeded；rejected → blocked→failed(`policy_denied`)（照 runApprovalTask L203-215 的已决分支） |
| 3 | ready 提升 | `promoteReady`（readiness.ts L71-159） | 直搬改造：`evaluateReady`（纯函数直搬）→ 单事务 CAS + `task.ready/task.blocked` 事件 |
| 4 | admission 门 | `isAdmissionClosed` L2347-2352（pause/graceful_stop/force_stop 关准入） | 同语义：run.controlIntent ∈ {pause, stop} → 跳过派发 |
| 5 | 队列构建 | `buildQueue` + BoundedQueue | 直搬（queueCapacity 上限；5 级优先级排序） |
| 6 | 并发派发 | `claimSpawnDrainCommit` L897-1094（H-WP11 并发 drive） | `dispatchLoop`：对 queue.drain() 每 entry 独立 `acquireSlot`（内存信号量）→ `claimTask`（单事务：ready→running 双 CAS + attempt 插入 + 事件）→ `executor.dispatch`（事务外）。**不变量 #1 继承**：每 attempt 独立终态，绝无 Promise.all 批量提交（drain 派发是并发屏障，收割逐个独立） |
| 7 | 收割 | （源在 drive 内 await） | `harvestSettled`：reflect-promise 已 settle 的 attempt 逐个 `commitTerminal`（§4.5） |
| 8 | 失败传播 | `propagateDownstream`（readiness.ts L165-203） | 直搬：failed + block_downstream → 下游 blocked(upstream_failed) |
| 9 | Run 终态投影 | `finalizeRunIfDone`（scheduler-driver.ts L401-489） | 直搬语义：全任务终态（或 only-dead-blocked）→ 聚合 anyFailed→failed / allCancelled→cancelled / 否则 succeeded；同事务 `run.<target>` 事件；pause 意图下不 finalize（FINALIZE_BLOCKING_INTENTS 同款） |
| 10 | pause 排空 | `drainToPaused` L758-810 | 直搬：pausing + 无 non-terminal attempt → paused（同事务 run.paused） |

### 5.2 `dag_tick` 的多轮与停点（D10）

```
tick(runId, {maxRounds = 4, settleMs = 10_000}):
  settleBudget = settleMs               // 总预算（非每轮预算）：全调用累计等待 ≤ settleMs
  noSettleStreak = 0
  for round in 1..maxRounds:
    progress = oneRound(runId)          // 返回 {promoted, dispatched, terminal, propagated}
    if runState(runId) ∈ terminal: break
    if progress > 0: noSettleStreak = 0; continue
    pending = inFlight 中该 run 的未 settle attempt
    if pending.isEmpty: break                      // 静默停点：等外部（审批/人工/上游）
    if settleBudget <= 0 or noSettleStreak >= 2: break   // 预算耗尽 或 连续 2 轮等待零 settle
    waited = await boundedRace(pending.map(reflect), min(settleMs, settleBudget))
    settleBudget -= waited.actualMs
    noSettleStreak = waited.anySettled ? 0 : noSettleStreak + 1
  return tickSummary                    // §8.3 返回形状
```

**停点与预算的硬保证**：单次 `dag_tick` 最长阻塞 = 各轮 reconcile 耗时 + **`settleMs`（全调用累计总预算）**——预算单调扣减、不随轮重置（否则 16 轮 × 60s = 16 分钟，违背 60s 上限初衷）。三重防自旋：① `settleBudget` 总预算；② `noSettleStreak >= 2`（连续两轮等待零 settle 即退——长任务未到点，模型该去干别的，下次 dag_tick 再收）；③ maxRounds 本身。`boundedRace` 返回实际等待时长（settle 提前返回或超时到点），预算按实扣。模型侧契约：`waiting_on: 'in_flight_attempts'` + `next_hint` 明示「稍后再 tick」——tick 的等待是**顺手捎带**，不是义务泵。

对照 `SchedulerDriver.driveToCompletion`（scheduler-driver.ts L243-381）三停条件的 DSH 等价：① Run 终态 → 同；② 零进展死锁守卫 → 收窄为「零进展且无 in-flight 且无 pendingWork 或 waitingExternal（approval park）」→ break；③ 迭代上限 → maxRounds（模型可传，默认 4，上限 16——一次工具调用不该内嵌万轮循环；DSH 的驱动循环是**跨工具调用**的：模型反复 dag_tick）。`settleMs` 让一次 tick 调用大概率看到长任务落地（改善「tick 返回 running → 模型干等」的 UX），上限 60s 防 tick 调用本身超时。

### 5.3 事务形状（不变量 #3/#6 的 sqlite 落地）

```js
store.tx(() => {                       // BEGIN IMMEDIATE ... COMMIT（node:sqlite 同步事务）
  // 投影变更（tasks/attempts/runs UPDATE ... WHERE state=? AND version=? —— CAS）
  // + events INSERT（type, payload, prev_hash, hash = sha256(prev_hash ∥ canonical(payload))）
  // 同一事务，缺一即回滚
})
// 资源释放在事务外（对照 terminal-commit.ts L257-261 的「terminal CAS inside txn; release outside」）
```

`claimTask`（对照 scheduler-loop L1943-2056 的 H1 修复）：事务内重读 task 行（防 TOCTOU）、`hasNonTerminalAttempt` 检查（不变量：每 task 至多一个非终态 attempt）、ordinal = prior max + 1、ready→running CAS（version 递增），attempt 行 + `attempt.claimed` 事件同事务。

### 5.4 资源准入（C7 并发自建，D11）

- **agent 槽**：`Admission { maxRunning: number, held: Set<slotKey> }`——`tryAcquireSlot()` 返回 null 则 task 留在 ready（下轮重评；对照 process-slots.ts `tryAcquireProcessSlot` L53-71 的「N 次单键尝试取任一空槽」语义，内存版即 `held.size < max`）。上限 = `run.limits.maxRunningAgents ?? config.defaultMaxRunningAgents(4)`，范围 1..32（照 Limits 表）。
- **shared_key 会话互斥**：`sessionKeys: Map<string, attemptId>`——同 key 同时至多一个持有者（对照 `acquireSessionLeases` L1158-1186 + tick 内 `launchedSessionKeys` 串行化 L607-629）；冲突者不派发留 ready。
- **为何不持久化租约**：task-weaver 的持久租约服务于「崩溃后判谁的 claim 还有效」；本插件崩溃语义 = **宿主退出 ⇒ in-flight 全部 orphaned**（§12），恢复后没有任何东西需要「续租」——持久租约没有消费者。内存信号量 + 单进程 = 同等防并发效果，少一张表两个失败模式。诚实代价：多 dsh 实例并发写同库不受保护（O5，README 声明）。

### 5.5 与 DSH background jobs / 自 Timer 的关系（契合度论证）

- **不注册 ctx.jobs job kind**：JobRegistry.start 需要 controller 附着（§2.2），且 job 的生命周期语义（一次性后台作业）与 DAG 的「跨多 tick 的状态机」不合身——把 DAG 塞进 job 是把状态机藏进作业管理器，反而丢掉「模型可见的泵」。
- **宿主进程即调度进程**的正确姿势：**泵 = 工具调用**（模型或自动化按需 dag_tick），辅以 `ctx.effect(() => setInterval(autoTick, autoTickMs))`（config，**默认 0=关**）。autoTick 只做**免派发 reconcile**（收割已 settle 的 in-flight / 审批提升 / 传播 / finalize——这些不需要 live parent Agent）；**不派发新任务**（dispatch 需要 `exec.agent`，Timer 上下文没有；硬要派发得缓存 Agent 句柄跨重启，违背随宿主生死模型）。派发永远发生在某次工具调用的 exec 内——这是与宿主模型契合的诚实边界，写进 README。
- M1 甚至不开 autoTick（模型驱动足够，tick 幂等）；M2 把 autoTick 作为可选配置落地（收割无人泵时的已完成任务）。

---

## 6. 持久化（核心问题 3）

### 6.1 选型论证：node:sqlite（D9）

**本插件的存在理由是「投影+事件同事务」**（不变量 #3/#6；task-weaver 用 bun:sqlite 事务实现，分析 §1「状态变更与 Event 同事务（hash 链）」）。三个候选：

| 方案 | 投影+事件原子性 | 断点续跑 | 结论 |
|---|---|---|---|
| JSON 状态文件 + JSONL 事件（worktrees 模式） | **破坏**：两个文件无法原子双写——崩溃窗口产生「投影已变、事件缺失」（或反），hash 链断裂且无法区分「崩溃」与「损坏」 | 可（加载投影） | 否决：对 worktrees 成立是因为其队列低频且以 promise 链为串行域；DAG 的事件流是审计与恢复的**共同事实源**，不能容忍分叉 |
| 纯 JSONL 事件日志（event-sourcing，状态=重放） | 单 append 近似原子（单行 write + fsync） | 可（全量重放） | 否决：① 每次 tick 全量重放开销随事件数线性涨；② append 的原子性依赖单次 write 系统调用不分裂——对长 payload 无保证；③ 投影查询（dag_status）需要随时物化 |
| **node:sqlite 单库**（投影表 + 事件表同库同事务） | **真原子**：`BEGIN IMMEDIATE ... COMMIT` | 可 | **选定**：DSH 自家先例（dsh-session-query-sqlite，§2.2）；DatabaseSync 同步 API 使进程内事务天然串行，无 async 竞态面 |

**JSONL 的位置**：导出/审计的后续可选（`dag_status(events: true)` 可直接查事件表，JSONL 导出器 M3 后置）——不是事实源。

**engines**：`>=22.13`（node:sqlite 在 22.x 后期免 flag 可用；DSH 宿主自身带 dsh-session-query-sqlite，用户运行环境已满足；本机实测 Node v24.19.0，分析 §6）。动态 `await import('node:sqlite')`，失败 loud 拒启（不静默降级 JSON——红线：无静默降级）。

### 6.2 Schema（v1）

```sql
PRAGMA journal_mode = WAL;  PRAGMA busy_timeout = 5000;
PRAGMA application_id = <dag 魔数>;  PRAGMA user_version = 1;

runs(run_id TEXT PRIMARY KEY, name TEXT, spec_json TEXT NOT NULL, spec_hash TEXT NOT NULL,
     state TEXT NOT NULL, control_intent TEXT, parent_session TEXT, base_cwd TEXT NOT NULL,
     created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL, version INTEGER NOT NULL)

tasks(run_id TEXT NOT NULL, task_id TEXT NOT NULL, state TEXT NOT NULL, version INTEGER NOT NULL,
      blocked_reason TEXT, retry_not_before INTEGER, updated_at INTEGER NOT NULL,
      PRIMARY KEY(run_id, task_id))

attempts(attempt_id TEXT PRIMARY KEY, run_id TEXT NOT NULL, task_id TEXT NOT NULL,
         ordinal INTEGER NOT NULL, state TEXT NOT NULL,          -- claimed|running|succeeded|failed|cancelled|orphaned
         backend TEXT NOT NULL, child_session TEXT,              -- SubagentRun.id（恢复时的会话定位线索）
         started_at INTEGER NOT NULL, updated_at INTEGER NOT NULL,
         stop_reason TEXT, failure_json TEXT, result_json TEXT,
         UNIQUE(run_id, task_id, ordinal))

events(event_id TEXT PRIMARY KEY, run_id TEXT NOT NULL, seq INTEGER NOT NULL,
       type TEXT NOT NULL, at INTEGER NOT NULL, task_id TEXT, attempt_id TEXT,
       payload_json TEXT NOT NULL, prev_hash TEXT NOT NULL, hash TEXT NOT NULL,
       UNIQUE(run_id, seq))                                      -- seq 单调 = 链序

approvals(approval_id TEXT PRIMARY KEY, run_id TEXT NOT NULL, task_id TEXT NOT NULL,
          action TEXT NOT NULL, state TEXT NOT NULL,             -- pending|approved|rejected
          note TEXT, created_at INTEGER NOT NULL, decided_at INTEGER)

outputs(run_id TEXT NOT NULL, task_id TEXT NOT NULL, name TEXT NOT NULL,
        value_json TEXT NOT NULL, produced_by_attempt TEXT NOT NULL, created_at INTEGER NOT NULL,
        PRIMARY KEY(run_id, task_id, name))
```

状态机（直搬 task-weaver 词汇——`TASK_TRANSITIONS` / `ATTEMPT_TRANSITIONS` / `RUN_TRANSITIONS` 三表照 domain 状态机源；收窄掉 adapter 域的 verifying/starting/stopping 等中间态）：

```
Task:   pending ──▶ ready ──▶ queued ──▶ running ──▶ { succeeded | failed
           │          │  ▲      │         │   │              | retry_wait }
           ▼          │  │      ▼         │   │                  ▲    │
        blocked ◀─────┘  │  cancelled ◀───┴───┴────────────────────┴────┘
           ▲    │        （四态均可取消：pending/ready/queued/running；running 的取消
           │    ▼          经 abort in-flight → attempt cancelled → task cancelled，§8.4 stop）
           │  cancelled
           └── retry_wait（backoff 期间上游失败：propagateDownstream 直写，见下注）
           blocked ──▶ ready（重评提升；approval_pending/merge_conflicted 等 park 不自动重评）
Attempt: claimed ──▶ running ──▶ { succeeded | failed | cancelled | orphaned }
                      （每 task 至多一个非终态 attempt——不变量照 L1984；
                        attempt 一旦终态不回退，重试 = 新 ordinal 的新 attempt）
Run:    running ──▶ { pausing ──▶ paused ──▶(resume)──▶ running
                    | cancelling ──▶ cancelled
                    | succeeded | failed }        —— finalizeRunIfDone 聚合规则照 scheduler-driver L447-458
```

**两条与源 `TASK_TRANSITIONS`（domain/src/task.ts L28-38）的诚实出入（CHECK 约束按本图写，不照源表）**：
1. **`running→cancelled` 保留**——源表确有（`running: [retry_wait, succeeded, failed, cancelled]`）；本插件消费方是 §8.4 `dag_control(stop)`（abort in-flight → attempt cancelled → task cancelled）与 §12 对账路径。前版图漏画此边，是绘图笔误非设计意图。
2. **`retry_wait→blocked` 刻意保留**——源**表**只写 `retry_wait: ["ready"]`，但源**码**的 `promoteReady`（readiness.ts L135-140）与 `propagateDownstream`（L185-192）都以原生 SQL CAS 把 retry_wait 行改写成 blocked（上游在退避期间失败的真实场景），即源的有效转移图含此边而声明表漏登——raw CAS 不经 `applyTransition` 合法性检查。本设计把它显式合法化：语义必需（否则退避中的任务在上游失败后永远卡在 retry_wait 轮询）。

**迁移收窄说明**：源 Task 状态机含 `ready→queued→running` 两跳（claimTask L2006-2029 的双 CAS + `task.queued` 事件），本设计**保留 `queued` 中间态**（DAG 库 CHECK 约束与迁移测试都要它），但引擎实现可在单事务内一次走完两跳（事件照发 `task.queued` + `task.running` 两条——事件序列与源逐字一致，投影行数少一次 CAS 往返）。源 Attempt 的 `starting`/`verifying` 中间态（`advanceAttemptWithEvents` L2046-2049 / verify 阶段）在 subagent 语境无观测面，收窄掉；`orphaned` 终态保留（§12 崩溃对账产物）。同态重写（from===to）按源 `applyTransition` 语义视为幂等成功——崩溃/重放的合法安全网，不构成非法边。

### 6.3 Hash 链（D12）

每 run 一条链：`hash = sha256(prev_hash ∥ '\n' ∥ canonical_json({seq, type, at, task_id?, attempt_id?, payload}))`，创世 `prev_hash = '0'.repeat(64)`。**同事务**推进（events INSERT 时计算）。加载时 `verifyChain(runId)` 全量重算——失配 → `logger.fatal` + 拒绝加载该 run（其余 run 不受累）+ 明确修复指引（删库重来 or 人工核对 events 表）。这是「投影+事件同事务」的可审计伴生物：链断了 ⇒ 一定有人在事务外写过 events 表。

### 6.4 并发与多实例

- 单宿主进程 = 唯一写者（engine 单例闭包 + DatabaseSync 同步事务）。
- WAL + `busy_timeout=5000`：另一进程恰在写时本进程读不崩；**跨实例并发写语义不支持**（O5）：两 dsh 同时 dag_tick 同一库 → 后写者 busy 超时 loud 失败（可接受的失败模式：不损坏、不静默）。README 明示「一个 DAG 库只经一个 DSH 宿主操作」。
- 文件：`~/.dsh/dag-orchestrator/dag.db`（0600，`wx` 独占创建，`application_id` 所有权守卫——dsh-session-query-sqlite L52-82 同款三件套）。

---

## 7. WorkflowSpec 子集（核心问题 4）

### 7.1 裁剪总表（源字段 → 留/砍 + 理由）

**根字段**：`version`(留，恒 1) / `name`(留) / `description`(留) / `project`(**改造**：`{root?, baseRef?}`——root 即 baseCwd 缺省源；无 mode/auto 探测，git 性质由 worktree/merge 节点显式表达) / `limits`(留 2 项) / `tasks`(留) / `labels`(砍，无消费方)。未知根字段拒绝（照 workflow-spec.md L148）。

**Limits**：`maxRunningAgents`(留，源 maxRunningProcesses 改名——不再是进程而是 subagent 并发) / `queueCapacity`(留)；砍 `maxRunDurationMs`/`maxTotalAttempts`/`maxOutputBytesPerAttempt`（budget 域不迁移；每 attempt 已有 timeoutMs）。

**Task 公共字段**：

| 源字段 | 处置 | 理由 |
|---|---|---|
| `id` | 留（`[a-z][a-z0-9-]{0,62}` 照 L181） | |
| `kind` | 留，收窄 `agent / approval / merge`（M1: agent；M2: +approval；M3: +merge）；**砍 verify kind**（验证建为 agent 任务的 outputSchema 契约门，§7.3） | VerifyService/子进程执行面不迁移 |
| `dependsOn` | 留（`{taskId, condition: succeeded|completed}` 两值枚举原样；**不引入表达式语言**） | |
| `inputs` | 留，语法改 `task://{producer}/{name}` | artifact 体系不迁移，outputs 表直查 |
| `outputs` | **改造**：`[{name, schema, required?}]`——schema 是 **ObjectJsonSchema 子集**（直通 `SubagentStartRequest.outputSchema`）；MVP 每 task 至多 1 个 output（loud） | 结构化结果即产物 |
| `isolation` | **砍**（read_only/worktree/direct 三模式体系不迁移）；写意图由 `worktree: {task, baseRef?}` 显式声明表达（M3） | worktrees 插件管隔离 |
| `workspaceFrom` / `workspaceLineage` | 砍（无 lineage 租约体系；worktree baseRef 显式给） | |
| `session` | 留 `shared_key` 语义一种：`concurrencyKey: string`（跨 task 互斥组）；砍 fresh/same_task（DSH 子代理天然 fresh） | |
| `timeoutMs` | 留（默认 1_800_000 照 L190；engine AbortController 实现） | |
| `retry` | 留全五字段（maxAttempts/backoffMs/maxBackoffMs/jitterRatio/retryOn） | shouldRetry 直搬的输入 |
| `failurePolicy` | 留（`block_downstream` 默认；另一值 `isolate` = 不阻塞下游——源 spec 枚举里 propagateDownstream 只处理 block_downstream，isolate 即无操作，本设计显式命名） | |
| `priority` / `concurrencyKeys` | priority 留（-100..100，队列第 3 级）；concurrencyKeys 并入上面的单 `concurrencyKey` | |
| `sandbox` / `substrate` / `agentProfile` / `verify` / `approval` | sandbox/substrate 砍（无 SandboxProvider/基座路由）；agentProfile **改造**为平铺委派字段（backend/role/model/provider/persona/toolFilter/cwd/maxTokens/maxDepth/delegation——对齐 subagents 工具参数面 §2.3）；approval 留 `{action, prompt?}` | |

**任务书点名的裁剪项**核对：artifact schema 校验（砍——outputSchema 即校验）、budget（砍）、watchdog（砍——engine timer 管超时）、circuit-breaker（砍）、adapter 健康度（砍）——与上文一致。

### 7.2 MVP Spec JSON 形状（dag_plan 的 `spec` 参数）

```jsonc
{
  "version": 1,
  "name": "refactor-auth",
  "description": "Parallel refactor with review gate and integration",
  "project": { "root": "/abs/repo", "baseRef": "HEAD" },          // root 缺省 = 会话 cwd
  "limits": { "maxRunningAgents": 3, "queueCapacity": 16 },
  "tasks": [
    { "id": "analyze", "kind": "agent", "prompt": "…",
      "outputs": [{ "name": "analysis",
        "schema": { "type": "object", "additionalProperties": false,
                    "properties": { "summary": { "type": "string" },
                                    "riskFiles": { "type": "array", "items": { "type": "string" } } },
                    "required": ["summary"] } }] },
    { "id": "impl-core", "kind": "agent",
      "dependsOn": [{ "taskId": "analyze", "condition": "succeeded" }],
      "inputs": ["task://analyze/analysis"],
      "model": "kimi-code/k3", "persona": "…", "delegation": false,
      "retry": { "maxAttempts": 3, "backoffMs": 5000, "maxBackoffMs": 60000, "retryOn": ["transient_network"] },
      "timeoutMs": 1800000 },
    { "id": "impl-docs", "kind": "agent",
      "dependsOn": [{ "taskId": "analyze", "condition": "succeeded" }] },
    { "id": "gate", "kind": "approval",
      "dependsOn": [{ "taskId": "impl-core", "condition": "succeeded" }],
      "approval": { "action": "approve_integration", "prompt": "两个实现分支已就绪，是否继续集成？" } },
    { "id": "integrate", "kind": "merge",                                             // M3
      "dependsOn": [{ "taskId": "gate", "condition": "succeeded" }],
      "merge": { "integrationBranch": "dsh-wt/integration/<auto>" } }
  ]
}
```

**校验**（lib/spec-validate.js，zod strict + 结构规则）：未知键 fail；id 格式/唯一；dependsOn 引用存在、无自指、**无环**（DFS，复用 critical-path 的 downstream 构造）；inputs 的 producer 必须是直接/传递上游且声明了同名 output（对照 workflow-spec.md L241-243 DataRef 规则）；kind 字段矩阵（approval 禁 retry>1 照 L206；merge 需 ≥1 上游 commit 源——M3 由 worktree 任务关联推导）；`worktree.task` slug 全 spec 唯一（M3 终评 M-A——`dag.worktree_slug_conflict`：slug 命名**一个**任务的 worktree，复用是同任务 retry 语义，非共享原语）；错误返回稳定 code + JSON path（照 L326-341 形态：`dag.unknown_dependency` / `dag.cycle_detected` / `dag.kind_field_mismatch` …）。

### 7.3 「verify」的 MVP 建模（不新增执行器）

task-weaver 的 verify = VerifyService 跑 argv + test-report-v1 artifact + `evaluateVerifyGate` 收门。本插件：**验证 = 一个带 outputSchema 契约的 agent 任务**——

```jsonc
{ "id": "verify", "kind": "agent", "dependsOn": [{ "taskId": "integrate", "condition": "succeeded" }],
  "prompt": "在集成分支跑测试并报告……", 
  "outputs": [{ "name": "report",
    "schema": { "type": "object", "additionalProperties": false,
                "properties": { "status": { "enum": ["passed", "failed"] }, "failedFiles": { "type": "array", "items": {"type":"string"} } },
                "required": ["status"] } }],
  "verify": { "expectOutput": "report", "expectStatus": "passed" } }
```

`verify` 块可选：声明时终态提交前过 **`evaluateVerifyGate` 直搬改造**（verify-gate.ts L79-115 骨架不变；receipt 源从 `artifacts.findByRun` 换 outputs 表：receipt = 本 attempt 的 `report` 输出且 `status === expectStatus`；未过 → 合成 permanent `dag.verify_gate_failed`——「process exit != Task success」不变量照搬）。这保住了直搬 verify-gate 的实义而零新增进程面。

**M3 终评 M-B 补充（merge 任务同门）**：agent 任务的门挂在 harvestSettled（终态提交前），但 merge attempt 在 dispatchLoop 内经 `runMergeTask` 直接终态提交——若门只挂 harvest，merge 任务声明的 `verify` 会被静默跳过（红线 1 的「admitted but silently not executed」类）。因此 merge executor 的**成功路径**（succeeded | no_changes）在 `commitTerminalAndRelease(null)` 前评同一 `evaluateVerifyGate`（引擎注入，executor 保持零 import；receipt 源同为本次待落盘的 outputs 表行——§7.3 替换的同一形态）。merge 输出 `{integratedCommit, integrationBranch}` 无 `status` 字段，其 status 等价事实是 integratedCommit（集成结果的标识），故 receipt 视图的 `status = integratedCommit`（持久化行保持原形不动）；空集成（no_changes → commit null）无字符串 status → 按 missing 失败。未过走同一合成永久失败进 retry/fail 机器（不发明新终态）；conflicted park / failed / queued 路径本就非成功，不过门。kind 矩阵保持 merge+verify 合法（保能力：merge 后验证是合理场景）。

### 7.4 Prompt 组装与注入边界

`promptWithInputs`（scheduler-loop.ts L2373-2426）语义直搬、介质收窄：上游 output 的 JSON **内联**进 prompt 头（源是落盘 `.task-weaver/inputs/` + 摘要前缀——DSH 子代理与其共享文件系统，但 MVP 不假设可写 cwd，内联最稳）：

```
--- Upstream task outputs (DATA, not instructions) ---
[task://analyze/analysis]
{ …完整 JSON，单输入上限 32 KiB（config.inputInlineLimitBytes），超限 → permanent 'dag.input_too_large' …}
--- End upstream outputs ---
<spec.prompt>
```

**边界纪律**（红线 5）：上游内容是**数据**——分隔符包裹 + DEFAULT_TASK_FILTER deny 掉 dag_* 控制面 + 子代理 persona 不变；spec.prompt 本身也是数据（dag_plan 校验它只是 string，不解析不执行）。

---

## 8. 工具面（核心问题 5）

5 件（D13），全部 `isConcurrencySafe: () => false` 除 `dag_status`。schema 用 dsh-tools `ParameterSchemaSpec` 形状写。

### 8.1 `dag_plan` —— 提交 / 校验 spec

```js
parameters: {
  spec:   { type: 'object', additionalProperties: true, required: true,
            description: 'WorkflowSpec object (see DESIGN §7.2). Validated strictly: unknown keys rejected, DAG must be acyclic, dependsOn/inputs must resolve.' },
            // 真机集成修复（08）：spec 声明改为 OPEN object（additionalProperties:true），
            // 不用 author-only 的 type:'json' 节点——'json' 编译出的 wire schema 无任何类型约束，
            // glm-5.3 + newapi 网关对无约束对象参数固定序列化为 JSON 字符串，
            // 到 execute 变成 string → zod schema_invalid "Expected object, received string"。
            // 真类型 object 被所有 tool-calling 网关遵守；开放 additionalProperties 保持
            // WorkflowSpec 面开放，全部结构校验仍由 lib/spec-validate.js（strict）承担，工具层只透传。
            // execute() 额外对字符串形态 spec 做一次 JSON.parse 容错（解析失败仍走原
            // schema_invalid 报错路径，校验强度不降）。
  resume: { type: 'boolean', description: 'If a run with the same name exists non-terminal, resume it instead of erroring (default false → loud name_exists).' },
}
output.schema: { type:'object', additionalProperties:false, properties: {
  kind: { const:'plan' }, run_id: { type:'string', required:true },
  spec_hash: { type:'string', required:true },
  task_count: { type:'integer', required:true },
  initial_tick: { /* tickSummary 形状（内联 §8.3，plan 内联首轮泵） */ },
  warnings: { type:'array', items:{type:'string'} },        // 如 bridge 字段被拒的指引
}}
```

行为：resolveBaseCwd（repo-gate 形态门禁 §4.6）→ spec-validate（strict）→ 事务：runs 插入（state running）+ 全 tasks pending + `run.created` 事件 + 初始 tick（进度立现）。

### 8.2 `dag_status` —— 投影查询

```js
parameters: {
  run_id: { type:'string', description:'Omit to list all runs (summary rows).' },
  detail: { type:'string', enum:['summary','tasks','attempts','events'], description:'Projection depth (default tasks).' },
  task_id: { type:'string', description:'Filter to one task (detail=attempts/events).' },
  limit:  { type:'integer', description:'events tail window (default 50).' },
}
output: summary → runs[]{run_id,name,state,counts{pending,ready,running,succeeded,failed,blocked},created_at,updated_at}
        tasks  → + tasks[]{id,kind,state,blocked_reason?,attempts,ordinal,last_stop_reason?,retry_not_before?}
        attempts → + attempts[]{attempt_id,ordinal,state,backend,child_session,started_at,stop_reason?,failure?}
        events → + events[]{seq,type,at,task_id?,attempt_id?,payload}
```

### 8.3 `dag_tick` —— 一轮 reconcile 泵（核心）

```js
parameters: {
  run_id:   { type:'string', required:true },
  max_rounds: { type:'integer', description:'Inner reconcile rounds per call (default 4, max 16).' },
  settle_ms:  { type:'integer', description:'Bounded wait for in-flight attempts to settle when a round makes no progress (default 10000, max 60000).' },
}
output.schema: { type:'object', additionalProperties:false, properties: {
  kind: { const:'tick' }, run_id:{type:'string',required:true},
  run_state: { type:'string', required:true, enum:['running','pausing','paused','succeeded','failed','cancelled'] },
  rounds: { type:'integer', required:true },
  promoted:{type:'integer',required:true}, dispatched:{type:'integer',required:true},
  terminal:{type:'integer',required:true},  propagated:{type:'integer',required:true},
  in_flight: { type:'array', required:true, items:{type:'object',additionalProperties:false,properties:{
      task_id:{type:'string',required:true}, attempt:{type:'integer',required:true},
      started_at:{type:'integer',required:true}, elapsed_ms:{type:'integer',required:true} }}},
  waiting_on: { type:'string', required:true,
    enum:['nothing','in_flight_attempts','approval','external'],
    description:'nothing = quiescent & nothing runnable; in_flight_attempts = long tasks still running; approval = parked on dag_approve; external = blocked upstream.' },
  next_hint: { type:'string', required:true },   // "call dag_tick again after in-flight work settles" / "ask the user, then dag_approve" / "run is terminal"
}}
```

### 8.4 `dag_control` —— pause / resume / stop / 节点操作

```js
parameters: {
  run_id:  { type:'string', required:true },
  action:  { type:'string', required:true,
             enum:['pause','resume','stop','retry_task','cancel_task'] },
  task_id: { type:'string', description:'retry_task/cancel_task target.' },
  reason:  { type:'string', description:'Recorded on the control event.' },
}
output: { kind:'control', run_id, action, run_state, effected:[{task_id, from, to}] }
```

语义（对照 ADMISSION_CLOSED_INTENTS L466 + drainToPaused L758-810 + retry 事件语义）：`pause` → controlIntent=pause（关新派发，in-flight 继续）→ 排空后 paused；`resume` → 清 intent（paused→running）；`stop` → 意图 stop + **dispose 全部 in-flight controller**（abort → attempt cancelled → run cancelled）；`retry_task` → terminal-failed 或 blocked(upstream_failed) 的 task → retry_wait（立即；发 `task.retry_requested` 事件——不与 retryOn 预算混账，人工重试是显式动作）；`cancel_task` → pending/blocked → cancelled。**工具不直接改任务状态**——全部经 engine 事务 + 事件（红线 2）。

### 8.5 `dag_approve` —— 审批决策入口（DAG 内节点，非独立系统）

```js
parameters: {
  run_id: { type:'string', required:true },
  task_id:{ type:'string', required:true },
  decision:{ type:'string', required:true, enum:['approve','reject'] },
  note:   { type:'string', description:'Recorded with the decision (recommended: user rationale).' },
}
output: { kind:'approve', run_id, task_id, decision, task_state,   // blocked（下轮 tick 提升）或已提升终态
          approval_prompt }   // 回显该节点的 approval.prompt，便于对话中向用户复述
```

行为：task 必须 `blocked(approval_pending)` 且存在 pending approval → 事务：approvals 行 approved/rejected + `approval.decided` 事件 → **不直接改 task**；下一 `dag_tick` 的 `reconcileApprovals` 提升（approved→succeeded / rejected→failed `policy_denied`，各带事件）。幂等：重复决策同一节点 → loud `already_decided`。

### 8.6 典型组合序列（写进各工具 description 尾部）

```
① 纯 agent DAG（M1）：
  dag_plan(spec) → initial_tick {dispatched:3}
  dag_tick(run_id) ×N（waiting_on: in_flight_attempts → … → nothing, run_state: succeeded）
  dag_status(detail:'tasks') 终局核对
② 崩溃续跑（M2）：
  （DSH 重启；apply() reconcile 已把 in-flight 标 orphaned + task failed + 下游 blocked）
  dag_status → 看到 orphaned 痕迹 → dag_control(action:'retry_task', task_id:…) ×k → dag_tick ×N
③ 审批门（M2）：
  dag_tick → waiting_on: approval（gate 节点 blocked(approval_pending)）
  （向用户复述 approval_prompt → 用户表态）→ dag_approve(decision:'approve')
  dag_tick → gate succeeded → 下游派发
④ worktrees 深组合（M3）：
  dag_plan(spec 含 worktree 写任务 + merge 节点) → dag_tick（写任务派发前引擎自动
  worktree_create(origin:'dag')，subagent cwd=worktree path）→ … → merge 节点经
  worktrees 队列串行集成 → conflicted 时 DAG 节点 blocked(merge_conflicted)，
  worktree_queue(action:'resolve') 后 dag_control(retry_task) 该 merge 节点
```

---

## 9. 迁移对照表（核心问题 6：直搬清单 + 全量对照）

### 9.1 直接搬运三件（+ 第四件 M3）

| 源 | 行数 | 目标 | 改写点 |
|---|---|---|---|
| `critical-path.ts` | 33 | `lib/critical-path.js` (~30) | 仅类型抹除 + `WorkflowSpecV1` → 本插件 spec 形状（`dependsOn[].taskId` 字段同名） |
| `bounded-queue.ts` | 150 | `lib/bounded-queue.js` (~145) | 类型抹除；零逻辑改动（5 级 comparator 原样） |
| `verify-gate.ts` | 119 | `lib/verify-gate.js` (~110, M3) | `VerifyGateDeps.artifacts/artifactService` → outputs 表查询端口；`AgentFailure` → 本插件 failure 形状；receipt 语义（本 attempt 绑定 + expectStatus）不变 |
| `types.ts` | 62 | `lib/types.js` (~60) | BlockedReason/ReadyEvaluation/TaskGraphSnapshot/TaskGraphTaskView 原样 |

（源三件合计 302 行 lib；任务书「~550 行」口径 = 含其测试。测试随迁见 TASKS。）

### 9.2 全量对照（源文件 → 目标 → 处置 + 理由）

| 源文件（行数） | 目标模块 | 处置 | 一句话理由 |
|---|---|---|---|
| `scheduler-loop.ts` (2959) | `lib/engine.js` (~700) + `lib/executor.js` (~180) + `lib/terminal-commit.js` (~140) | **吸收重写** | tick 14 步序、三不变量、claimTask/commitTerminal 的 CAS+同事务事件语义、shouldRetry 逐函数保留；spawn/drain/heartbeat/ProcessRecord/watchdog/circuit/budget/review 九个域换绑或裁掉（§4/§5） |
| `terminal-commit.ts` (262) | `lib/terminal-commit.js` (~140) | **语义直搬** | 「commitTerminal(校验 owner) → 事件 → task CAS 同事务；租约外释；retry 分支先 Attempt 终态再 task→retry_wait（Issue 5 顺序 L106-125）」逐条保留；租约部分收窄为内存信号量释放 |
| `readiness.ts` (231) | 并入 `lib/engine.js`（promoteReady/propagateDownstream/buildQueue ~150） | **直搬改造** | ServiceContext → DagStore；evaluateReady 纯函数化调用不变；dependencyGateNotMet 事件保留（gate 算子 M3 随 verify 一起，M1 无 gate 声明） |
| `ready-evaluator.ts` (444) | `lib/ready-evaluator.js` (~280) | **直搬收窄** | evaluateReady/upstreamSatisfies/isReadySource/READY_BLOCKED_CODES 原样；裁 sandboxResolver/profileResolver/gateEvaluator（无对应体系；M3 gate 随 verify 回归 evaluateGate 五算子） |
| `process-slots.ts` (71) | 并入 `lib/admission.js`（~60） | **语义直搬** | 「N 槽取任一空位；满则留 ready 下轮重评」语义内存化；键不再持久化 |
| `resource-admission.ts` (250) | —— | **裁掉** | D11：持久租约无消费者（崩溃 ⇒ 全 orphaned）；all-or-nothing 语义在单进程内存信号量下平凡成立 |
| `scheduler-driver.ts` (553) | 并入 `lib/engine.js`（tick 多轮 ~80）+ finalizeRunIfDone (~70) | **语义直搬** | 三停条件 + 聚合终态 + FINALIZE_BLOCKING_INTENTS + isSoftBlocked 保留；while 循环改有界 maxRounds（DSH 泵=工具调用） |
| `task-executors.ts` (322) | `lib/executors/approval.js` (~90, M2) + `lib/executors/merge.js` (~110, M3) | **approval 直搬语义 / merge 改造** | approval：request→park→已决三分支照 L191-256；merge：MergeQueuePort→worktrees 引擎单例，enqueue→drain 循环→五态映射照 runMergeTask L108-185；verify 执行器裁掉（§7.3 契约门替代） |
| `parking-policy.ts` (437) | approval park 语义并入 executors/approval.js | **裁掉大部** | adapter_unavailable / review_pending 两 park 无对应体系；approval park 的「commit attempt failed → CAS task blocked(approval_pending) → 事件，同事务；槽外释」形状保留 |
| `capacity-governor.ts` (103) | —— | **裁掉** | budget 域不迁移 |
| `index.ts` (75) | —— | **裁掉** | 插件入口是 apply() |
| `recovery-service.ts` (1269, application 层) | `lib/recovery.js` (~220) | **分类学直搬 + 全面收窄** | §12：五分类决策树映射到 subagent 会话语境；singleton/marker/probe/stop 四端口按 DSH 语义重写或裁掉 |

**规模核算**：直搬/直搬改造 ≈ 900 行（含 302 直搬 + readiness/terminal/driver 语义段）；新写 ≈ 2,200 行（store 380 / engine+driver 850 / executor+executors 380 / tools 600）；lib 合计 **~3,100**；test **~2,400**（TASKS 详列）。源 6.1k+1.3k → 净裁 ~55%（budget/watchdog/circuit/review/adapter/进程治理全域出清）。

---

## 10. 安全红线（12 条，实现期进 AGENTS.md）

1. **Spec 校验 strict**：zod strict + 结构规则（无环/引用完整/kind 矩阵）；未知键、未知依赖、未知 condition 一律 loud 拒绝（`dag.schema_invalid` 族），绝不猜测降级执行（对照 workflow-spec.md L359-361「不得猜测或降级执行」）。
2. **状态只能经引擎事务变更**：五个工具无一直接 UPDATE 投影表——dag_approve 只写 approvals 表 + 事件，提升归 tick；一切投影变更发生在 `store.tx()` 内且伴随事件（不变量 #6 机械 enforced：engine 是唯一持有 tx 入口的模块，lint 静态检查 `lib/` 内 sqlite 调用仅出现在 `dag-store.js`）。
3. **投影 + 事件 + hash 同事务**；加载时全链校验，失配拒载该 run（fail closed，§6.3）。
4. **崩溃对账先于工具注册**（分析 §4-C4）：apply() 顺序 = config → store.open+链校验 → reconcile → 注册工具；对账未完成前没有任何 dag_* 工具可被调用。
5. **防注入边界（prompt 是数据）**：上游 output 与 spec.prompt 经分隔符包裹内联；DAG 任务子代理默认 `toolFilter deny [dag_*, subagent, subagent_fork]`——**任务代理不能操作 DAG 控制面、不能再委派**（spec 显式 `delegation:true` 才放开后者，前者永不放开）；审批决策只能由编排会话（人在环）经 dag_approve 做出。
6. **权限不越顶**：M1 只开 native 后端，spec 出现 `permission_mode`/`reasoning_effort`/bridge `backend` 即 loud error（§4.3 选项 A）——结构上杜绝绕过 subagents 委派天花板；bridge 放开时必须复用其 `PERM_RANK` 天花板校验（readonly<default<full，fail closed），此为 O2 的硬前提。
7. **持久化原子与所有权**：一切写经 `store.tx()`（BEGIN IMMEDIATE）；参数化 SQL（预编译 + 绑定参数，用户数据永不入 SQL 字符串——lint 加正则检查 `db.exec(` 仅允许 PRAGMA/DDL 常量）；库文件 0600 + `wx` + `application_id` 守卫；无 JSON 部分写。
8. **零网络**：插件自身不发任何网络请求（subagent 的工具使用由宿主沙箱治理，与本插件无关）；测试零网络零真实 CLI（node:test + fake executor/store，沿家族纪律）。
9. **cwd 门禁**：task.cwd 与 project.root 必须 realpath 后落在（workspaceRegistry ∪ run.baseCwd 子树 ∪ config.allowedRoots）；不接受 any-root 开关（worktrees repo-gate 同款 fail-closed 形态）。
10. **超时与资源上限**：每 attempt timeoutMs（AbortController + 定时器，定时器清理入 finally）；maxRunningAgents 1..32、queueCapacity 1..1024（照 Limits 表）；settleMs/maxRounds 有上限（防 tick 调用自旋）。
11. **输入内联上限**：单输入 32KiB（config 可调），超限 loud `dag.input_too_large`——宁可拒绝也不静默截断上游数据。
12. **config zod strict + engines >=22.13**；`node:sqlite` 动态导入失败 loud 拒启（无 JSON 静默降级）；apply() 返回 undefined；peer 双实例自检（C6）。

---

## 11. 与 dsh-worktrees 的组合（核心问题 8）

复用其 DESIGN §10 三道缝，反向落成 DAG 侧契约：

1. **merge 节点 → 队列复用**：`kind: merge` 的 executor（M3）：
   - 输入映射：merge 任务的 `dependsOn`（condition succeeded）中**带 worktree 声明的上游 agent 任务**的关联 worktree = merge 源（DAG 记录 dispatch 时创建的 worktree id）；不再有 git-commit-v1 artifact 中转（outputs 体系收窄，§7.1）。
   - 执行：对每源调 worktrees 引擎 `enqueue({worktreeId, integrationBranch, origin:'dag', correlationId: attemptId})` → `drain(repoKey, branch)` → 消费 DrainOutcome：`succeeded` → merge 任务 succeeded（outputs 记 integratedCommit）；`conflicted` → 任务 blocked(`merge_conflicted`, conflictFiles + retained worktree 引用)——**人工经 `worktree_queue(action:'resolve'|'retry')` 释放集成分支后**，`dag_control(retry_task)` 重跑该 merge 节点；`failed` → 失败按 retry 策略；`no_changes` → 视作 succeeded（空集成合法）；`queued(queued_ahead)` → 本轮不终态，下轮 tick 再 drain（对照 runMergeTask L135-159 的 applyNext 循环语义）。
2. **引擎单例获取（新增组合缝，需 worktrees 侧一天落地）**：dsh-worktrees 经 Cordis 服务面暴露其引擎：`ctx.provide` 一个命名访问器（建议 `worktreesEngine`，`{ getMergeQueue(), getWorktreeService(), available: boolean }`）；本插件用**机会主义探测** `ctx.get('worktreesEngine')`（apply 时与每次使用时各探一次；**不用 `inject`**——inject 会把本插件的加载阻塞到依赖可用为止，可选组合缝不应有此权力；DSH 官方 `ctx.get` 即为此模式，tool-bash/tool-subagent 同款先例）——缺席时 merge/worktree 任务 loud `dag.worktrees_unavailable`（对照 `scheduler.merge_queue_not_configured` L76-83），agent-only DAG 不受影响。**禁止**自建第二 merge-queue 实例指向同一 state.json（worktrees §10 明令）。
3. **写任务 worktree 归属**：`task.worktree: {task, baseRef?}` 声明 → **DAG 编排在 dispatch 前创建**（`getWorktreeService().create({task, repoRoot, baseRef, origin:'dag', correlationId: attemptId})`）→ path 作 subagent cwd；attempt 终态后 **DAG 不删**——worktree 生命周期（merge 收集/清理）全归 worktrees 工具与其 reconcile（其 §10「明确不做 DAG 侧生命周期接管」）。崩溃窗口：worktree 已建、attempt 未派发 → 对账见 orphaned attempt + 关联 worktree 记录 → 人工 `worktree_cleanup` 或重试后复用（`dag_control retry_task` 重派发时若 worktree 记录仍 active 则复用 path，不重复建）。**复用授权范围 = 同任务重派发**（M3 终评 M-A 双层收紧）：① 计划期——`worktree.task` slug 全 spec 唯一（`dag.worktree_slug_conflict`，结构性消灭并行同 slug）；② 运行期——复用仅当 active 记录的 `correlationId`（建时 attemptId）属于**本任务**的 attempt 历史（引擎 dispatch ctxInfo 传入 `taskAttemptIds`）；不匹配（他任务的 worktree）或无法证明归属（记录无 correlationId / 缺 attempt 历史）→ 保守不复用、走 create，后者对被占 slug 大声失败（transient `dag.worktree_create_failed`）——绝不静默共用检出（隔离破坏 + prompt 污染）。服务侧契约（worktrees-seam JSDoc）：`findActiveByTask` 返回 `{path, id?, correlationId?}`，correlationId 为可选的归属证据字段。

---

## 12. 崩溃恢复（核心问题 9）

### 12.1 DSH 语境的前提差异

C4（宿主退出杀全部子进程）+ 一次性 in-process 子代理随宿主死 ⇒ **不存在「controlled 存活进程」**：重启后没有任何 in-flight subagent 可以 reattach（无 handle、无 result 通道——对照 recovery-service「identity_proven_but_not_reattachable → bounded-stop + orphaned」L533-551 的悲观缺省，DSH 连 identity probe 都无对象）。因此五分类在 DSH 语境的映射：

| task-weaver 分类 | DSH 映射 | 判定 |
|---|---|---|
| `controlled` | **不可能出现** | 无 reattach 通道（如上）；设计上不设该分支，注释说明为何 |
| `no-process`（Window 1：claimed 未 spawn） | attempt `claimed`（派发前崩溃）| → failed（`recovery.no_dispatch`）——**唯一免人工的机器终态**（无可证副作用，对照 decideNoProcess L634-652 的 canReach('failed') 分支）；task 若非终态 → retry_wait 立即（**这里允许自动重试**：nothing ever ran，天然幂等——比源更宽一格，理由记录于事件） |
| `exited`（Window 3/4：进程亡、终态未提交） | attempt `running` + 无 in-flight promise（重启即此态） | → **orphaned**（非 failed！）：子代理可能已做半成品工作（worktree 脏树/半写文件），成功不可推断、副作用不可证——对照 decideExited「success cannot be inferred」+ bounded 政策「不为未知非幂等副作用自动发明回退」（L37-43）⇒ task failed + `recovery.action_requested`（人工：核对 worktree/产出后 `dag_control retry_task`） |
| `orphaned`（Window 2/8：身份不可证） | DSH 无 PID 语境 | 并入上一行（所有 running 崩溃痕迹统一 orphaned 语义） |
| `inconsistent`（Window 6：终态 attempt + 活进程记录） | 投影自检：终态 attempt 却有未收割的 inFlight 残迹（内存态重启后为空，此分类在纯持久层无对象）→ 转为 **链校验失败/孤儿 outputs 行**的审计发现 | 加载时 `verifyChain` + outputs 孤儿行（produced_by_attempt 非终态）→ logger.warn 审计清单，不阻塞（对照「surfaced for audit」） |

### 12.2 启动序列（apply() 内、工具注册前）

```
reconcile(store):
  1. verifyChain(每 run) —— 失配 → 该 run 标 state 'failed' + recovery.chain_broken 事件（其余 run 继续；工具注册后可见，人工处置）
  2. runs WHERE state 非终态:
       for attempt WHERE state ∈ {claimed, running}:
         claimed → tx{ attempt→failed(recovery.no_dispatch); task→retry_wait(now) + task.retry_scheduled 事件 }
         running → tx{ attempt→orphaned + attempt.orphaned 事件; task→failed + task.failed 事件
                       + recovery.action_requested 事件（含 child_session 供人工翻 DSH 会话日志核对）}
       run 若 pausing → 保持（下次 tick 的 drainToPaused 收口）；否则 running 不动
  3. （M3）worktrees 引擎若在场：其对账由其自身 apply 负责（两插件各自对账自己的状态；DAG 侧 orphaned attempt 的 worktree 引用留在事件里供人工）
  4. 汇总 logger.info（recovered runs / orphaned / auto-retried 计数）
```

**bounded 政策照搬**：唯一自动动作 = 「从未派发」的重试；一切「跑了但没跑到终态」→ 人工路由（`recovery.action_requested`）。不做补偿命令发明、不做「疑似成功」推断。

---

## 13. 工程量与实施顺序（核心问题 10）

里程碑切分（任务级拆解、验收标准、依赖图见 **`docs/TASKS.md`**）：

- **M1 最小闭环**（agent-only DAG 全链）：脚手架 → 直搬三件 → sqlite store（含链）→ spec-validate → engine 单轮（promote/dispatch/harvest/propagate/finalize）→ executor native → dag_plan/status/tick → apply 总装 + reconcile(claimed 分支)。
- **M2 重试与恢复**：terminal-commit 重试路径 + shouldRetry → dag_control（pause/resume/stop/retry_task/cancel_task）→ approval kind + dag_approve + reconcileApprovals → 崩溃对账全量（orphaned 路径）+ 链校验拒载 → autoTick 可选 Timer。
- **M3 深组合**：worktrees 引擎缝（inject + 缺席降级）→ worktree 声明任务（dispatch 前 create）→ merge kind executor（五态映射）→ verify 契约门（evaluateVerifyGate 直搬 + gate 算子）→ README 双语 + 组合示例。

行数级估算与任务工期见 TASKS.md §工程量预算。

---

## 14. 开放问题（已全部拍板 · 2026-08-16 用户裁决）

> 拍板结果：O1/O3/O4/O5/O6 均按设计倾向落定；O2 立项落地为 dsh-plugin-subagents 侧的引擎级 dispatch 缝（设计文档：`dsh-plugin-subagents/docs/dispatch-seam.md`，2026-08-16 落盘）。原问题与分析保留供追溯，拍板见最右列。

| # | 问题 | 本设计的倾向 | 影响 | 拍板（2026-08-16） |
|---|---|---|---|---|
| O1 | dispatch 的 parent 归属：恒挂当前 tick 调用方（D8 副产品）vs 强制 run 创建会话 | 挂当前泵者——实现无死角、跨会话续跑天然成立；代价：子代理 parentSession 记最后泵者，审计时 run.parent_session 仍指向创建者（runs 表已存） | 若要求血缘严格一致，需缓存创建者 Agent 或拒绝异会话 tick——复杂度↑ | ✅ 按倾向（挂当前泵者） |
| O2 | bridge 后端 settings 级派发（§4.3）：等 subagents 插件导出引擎级 `dispatchAgentTask({backend, settings,…})`（与 worktrees §10 同款缝）vs DAG 注册自有 wrapper provider（需 bridge 工厂可导入） | 前者——单一事实源、天花板校验留在 subagents 侧；本插件 M1 结构性只开 native，不阻塞 | bridge 任务（codex/claude/grok-native 跑 DAG 节点）全量后置；需向 subagents 提需求 | ✅ **立项落地**：subagents 侧导出引擎级 dispatch 缝（设计文档 `dsh-plugin-subagents/docs/dispatch-seam.md`）；M1 仍 native-only + bridge 字段 loud 拒绝，bridge 执行器在该缝实装后接入（M2+） |
| O3 | autoTick 默认值：0（关，纯模型泵）vs 30s（免泵收割） | M1 关 / M2 起默认 30s 且只做免派发 reconcile——「无人泵时已完成任务及时落账」，派发仍只在工具 exec 内 | 默认开会带来「DAG 在后台动状态」的心智负担；用户可关 | ✅ 按倾向（M1 关 / M2 默认 30s 只收割不派发） |
| O4 | `kind: verify` 是否独立（当前：agent+verify 契约门，§7.3） | 契约门——零新增执行面、verify-gate 直搬保义；代价：验证命令由子代理自己跑（受其沙箱治理）而非插件子进程 | 若要插件自有 argv 执行器（等价 VerifyService），需新增子进程纪律面（run.js 级），M3 后再议 | ✅ 按倾向（契约门） |
| O5 | 多 dsh 实例并发同库（与 worktrees O5 同立场） | 声明不支持 + WAL/busy_timeout 防损坏 + README 风险说明；后置 `withFileLock`（dsh-atomic-write 现成原语）跨进程串行 | 双开重度用户撞 busy 超时（loud，可接受） | ✅ 按倾向 |
| O6 | inputs 内联上限 32KiB 是否够 / 是否要落盘中转（对照 task-weaver 落盘 `.task-weaver/inputs/`） | 内联起步——DSH 子代理与其父共享 FS，落盘中转是纯优化，M3 后视真实 spec 体积再加 | 超大 output（如全量代码分析）需调 config 或后续落盘 | ✅ 按倾向（内联 32KiB 起步） |