@mzzsfy/dsh-rs-workflow 0.2.4 → 1.0.0

package/README.md

@@ -1,63 +1,28 @@
 # @mzzsfy/dsh-rs-workflow
 
-若水工作流 (rs-workflow) 一体化插件：GUI 配置、模型工具与 agent preset（工作流协议技能、编排引擎、模式组合）全部在一个包里。
+若水工作流 dsh 插件——设置面:流程模板管理与工作位/预算配置。模板编辑(host dryRun 权威校验)、只读详情、模板规范、六工作位与三预算配置读写。
 
-## 行角色
-
-| 行角色 | 所在平面 | 位置 | 作用 |
-|---|---|---|---|
-| `settings` | host | 包内 bundle patch（cordis.patch.yml） | 注册 settings 命名空间 `rs-workflow` → GUI 设置页出现表单（3 基础+13 细分工作位、默认模板、任务上限、预算（对齐 rs-tui 原始配置语义）），持久化于 `~/.dsh/settings.yaml` |
-| `preset-sync` | host | 同上 | 每次 dsh 启动把包内 `preset/rs-workflow` 幂等同步到用户预设根 → 模式选择器出现"若水工作流"，升级包后重启即更新 |
-| `tool` | agent | 释放出的 preset 组合（agent.cordis.yml） | 注册模型工具 `rs_workflow_config` → 主代理启动工作流编排前读取当前配置；skills/rs-workflow 协议技能（SKILL.md + engine.js 编排引擎 + slots.json5 后备配置）随 preset 一起分发 |
-
-## 安装
-
-```sh
-dsh plugin --profile web add @mzzsfy/dsh-rs-workflow
-```
-
-重启 dsh 后三件事自动发生：设置页出现 rs-workflow 表单；preset 释放到 `<dsh-home>/.agent-presets/rs-workflow`（含来源标记 `.dsh-rs-workflow-source.json`）；模式选择器出现"若水工作流"。无需手动编辑 cordis.patch.yml，无需手动拷贝 preset。
-
-preset 内 tool 行以裸包名引用本包（从 profile 目录上溯解析到 profile node_modules），包与 preset 始终由本包同时交付，不存在顺序问题。
+**编排运行时(driver/store/flow-exec/释放链)按 v5 设计(`docs/rsww-v5/`)实现。**
 
-## 升级
+模板文本为**严格 JSON**(有 GUI 编辑器,无 JSON5 需求);配置与模板存自有文件 `~/.dsh/dsh-rs-workflow/v5/`,**不经宿主 settings 服务,不写 settings.yaml**。
 
-同一命令重复执行即升级到最新发布版本，重启 dsh 后 preset-sync 自动把新版 preset 同步到预设根。
-
-## 卸载
+## 行角色
 
-```sh
-dsh plugin --profile web remove @mzzsfy/dsh-rs-workflow   # 或 pnpm remove（profile 内）
-rm -r ~/.dsh/.agent-presets/rs-workflow
-```
+| 行角色 | 作用 |
+|---|---|
+| `board` | `/api/rsww/*` 设置子域路由(模板 CRUD/校验/规范/配置读写),数据落 `~/.dsh/dsh-rs-workflow/v5/{templates,config}.json` |
 
-pnpm 不执行依赖的卸载脚本（preuninstall，pnpm 11 实测含 onlyBuiltDependencies 白名单均不放行），插件无法在自身被移除后自动清理，preset 残留会在模式选择器显示为 broken——按上面第二条命令手动删除即可。包内亦提供编程接口（从包根导入，exports 只开放 `.` 单一入口）：
+## 设置页路由
 
-```js
-import { presetDest, removePreset, syncPreset } from '@mzzsfy/dsh-rs-workflow'
-// presetDest(): 释放目标绝对路径（诊断 home 错位）
-// syncPreset(): 立即同步一次，返回 'created' | 'updated' | 'unchanged' | 'skipped-foreign'
-// removePreset(): 删除本包释放的 preset，返回 'removed' | 'missing' | 'foreign'
-```
+`/api/rsww/templates` `template` `template-save`(含 dryRun) `template-remove` `spec` `config` `config-save`
 
-## 冒烟测试
+## 开发
 
 ```sh
-node scripts/test-workflow-plugin.mjs
+node scripts/dev-link.mjs all      # 挂 junction 开发态
+node --test "test/*.test.mjs"      # 包内测试(在 packages/dsh-rs-workflow 下)
 ```
 
-默认测已安装副本，传入包目录路径可测任意构建；仓库内副本解析不了 peer 依赖（@deepseek-ai/* 从安装位置向上才找得到），需自备 node_modules。覆盖三个行角色：preset-sync（临时 DSH_HOME 内真实写盘 + 幂等）、settings（分层解析）、tool（执行路径）。
-
-## 行引用方式说明
-
-- 预设组合行的裸包名从组合 baseUrl（profile 目录）上溯 node_modules 解析
-  （`PresetTree.import` → `internal.import(specifier, baseUrl)`），profile
-  node_modules 在解析链上，所以预设行用裸 scoped 包名。
-- host 补丁行（bundle patch）的裸包名从安装锚点 / profile node_modules 解析，
-  两条链一致，补丁行同样用裸包名。
-- preset 技能发现走 skill-filesystem 的 `customSkillDirs`，以组合 `baseUrl`
-  （= 释放出的 preset 目录）定位 `skills/`，随 preset 同步走。
-
-## License
+## dsh 版本兼容
 
-MIT
+三版本全部通过:preset 释放、Agent 预设页若水工作流卡、rs_workflow_ 工具可列出、激活 live。

package/cordis.patch.yml

@@ -1,21 +1,12 @@
-# The rs-workflow bundle patch: registers the host-plane rows of the rs-workflow
-# all-in-one plugin into the profile root. Applied by
-# `dsh plugin add @mzzsfy/dsh-rs-workflow`:
-#   - rs-workflow / role settings: mounts the GUI settings form under the
-#     `rs-workflow` namespace in the settings page.
-#   - rs-workflow-preset-sync / role preset-sync: syncs the bundled preset
-#     (preset.yml + agent.cordis.yml + skills) into the user preset root on
-#     every boot, so the picker entry "若水工作流" ships with the plugin and
-#     follows plugin upgrades.
-# The tool-plane row (rs_workflow_config model tool) lives in the released
-# preset composition, not here: model-facing tools belong to the preset plane.
+# rs-workflow bundle patch:把本包 host 平面行注册进 profile 根
+# (`dsh plugin add @mzzsfy/dsh-rs-workflow` 应用):
+#   - rs-workflow-board / role board:挂载 /api/rsww/* 路由(设置页模板管理 + 配置)。
+# 模板与配置存自有文件 ~/.dsh/dsh-rs-workflow/v5/,不经宿主 settings 服务,不写 settings.yaml。
+# 编排运行时只存在于模式组合(preset/rs-workflow 骨架经 release 生成 rs-<id> 组合),
+# 宿主根不注册 orchestrator 行——编排属于会话,不属于全局。
 
 - insert:
-    - id: rs-workflow
+    - id: rs-workflow-board
       name: '@mzzsfy/dsh-rs-workflow'
       config:
-        role: settings
-    - id: rs-workflow-preset-sync
-      name: '@mzzsfy/dsh-rs-workflow'
-      config:
-        role: preset-sync
+        role: board

package/lib/board.mjs

@@ -0,0 +1,355 @@
+// board — /api/rsww/* 路由薄分发:数据权威态在 store 单例/自有文件存储(v5/{templates,config}.json)/driver 控制队列单例,路由无业务状态
+// 运行时路由 v5 恢复:runs/run/control(approve|reject 增 by/reason)/resume-from(种子续跑,不拉段)/run-remove/release/unrelease/released
+// 规划受理不经 HTTP:rs_workflow_start 是 orchestrator 工具行(见 feat/orchestrator.md)
+import { reportStore, ACTIVE_STATES } from './store.mjs'
+import { registry, post, initiatorOf, resumerOf } from './driver/control.mjs'
+import { validateTemplate, validateTemplateSet } from './template.mjs'
+import { releaseFlowTemplate, unreleaseFlowTemplate, releasedTemplateIds } from './release.mjs'
+import { SPEC_TEXT } from './spec.mjs'
+import { normalizeConfig, BUDGET_KEYS, SLOT_KEYS } from './settings-schema.mjs'
+import { loadJson, saveJson } from './storage.mjs'
+
+const BODY_MAX_BYTES = 256 * 1024
+
+function sendJson(res, status, payload) {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' })
+  res.end(JSON.stringify(payload))
+}
+
+function rejectCrossOrigin(req, res) {
+  const origin = req.headers ? req.headers.origin : undefined
+  if (!origin) return false
+  let sameOrigin = false
+  try {
+    sameOrigin = new URL(origin).host === req.headers.host
+  } catch {
+    sameOrigin = false
+  }
+  if (sameOrigin) return false
+  sendJson(res, 403, { error: '跨源请求被拒绝' })
+  return true
+}
+
+function rejectNonJson(req, res) {
+  const contentType = req.headers ? String(req.headers['content-type'] || '') : ''
+  if (contentType.includes('application/json')) return false
+  sendJson(res, 400, { error: 'content-type 须为 application/json' })
+  return true
+}
+
+function guardedRoute(handler) {
+  return async (req, res) => {
+    try {
+      if (req.method !== 'GET' && req.method !== 'POST') {
+        sendJson(res, 405, { error: 'method not allowed' })
+        return
+      }
+      if (req.method === 'POST') {
+        if (rejectCrossOrigin(req, res)) return
+        if (rejectNonJson(req, res)) return
+      }
+      await handler(req, res)
+    } catch (error) {
+      // errors 数组(逐条 target:message)随响应透传,GUI 编辑器据此逐条定位
+      const body = { error: error && error.message ? error.message : String(error) }
+      if (Array.isArray(error?.errors)) body.errors = error.errors
+      sendJson(res, 400, body)
+    }
+  }
+}
+
+// POST-only 变体供无读面的写路由使用:GET 放行会让跨站 <img src> 无守卫驱动改写
+guardedRoute.post = (handler) => async (req, res) => {
+  if (req.method !== 'POST') {
+    sendJson(res, 405, { error: 'method not allowed' })
+    return
+  }
+  return guardedRoute(handler)(req, res)
+}
+
+function readJsonBody(req) {
+  return new Promise((resolve, reject) => {
+    let size = 0
+    const chunks = []
+    req.on('data', (chunk) => {
+      size += chunk.length
+      if (size > BODY_MAX_BYTES) {
+        reject(new Error('请求体超过上限'))
+        req.destroy()
+        return
+      }
+      chunks.push(chunk)
+    })
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')))
+    req.on('error', reject)
+  })
+}
+
+// ── 模板读写(自有文件存储) ──────────────────────────────────────────────────
+function rawTemplates() {
+  return loadJson('templates.json', [])
+}
+
+function readTemplates() {
+  return rawTemplates()
+}
+
+function writeTemplates(templates) {
+  saveJson('templates.json', templates)
+}
+
+function removeTemplateById(id) {
+  const raw = rawTemplates()
+  const next = raw.filter((t) => t.id !== id)
+  if (next.length === raw.length) return { ok: false, error: '模板不存在: ' + id }
+  writeTemplates(next)
+  // 撤下释放物:删除模板即移除对应释放目录(外来目录返回 foreign 不动)
+  const outcome = unreleaseFlowTemplate(id)
+  return { ok: true, outcome }
+}
+
+function parseTemplateEntry(id, body) {  const json = typeof body.json === 'string' ? body.json : ''
+  let parsed
+  try {
+    parsed = JSON.parse(json)
+  } catch (error) {
+    const err = new Error('模板 JSON 解析失败:' + (error?.message ?? error))
+    err.errors = [{ target: 'json', message: String(error?.message ?? error) }]
+    throw err
+  }
+  const errors = validateTemplate(parsed)
+  if (errors.length > 0) {
+    const err = new Error('流程模板校验失败:' + errors.length + ' 条')
+    err.errors = errors
+    throw err
+  }
+  if (parsed && typeof parsed.id === 'string' && parsed.id !== id) throw new Error(`id 不一致: 模板 "${id}" vs 定义 "${parsed.id}"`)
+  return { parsed, json }
+}
+
+function configSavePatch(body) {
+  const patch = {}
+  const problems = []
+  if (body.slots !== undefined) {
+    if (typeof body.slots !== 'object' || body.slots === null || Array.isArray(body.slots)) {
+      problems.push('slots 须为对象')
+    } else {
+      const slots = {}
+      for (const [key, value] of Object.entries(body.slots)) {
+        if (!SLOT_KEYS.includes(key)) {
+          problems.push(`未知槽位键:${key}`)
+          continue
+        }
+        if (typeof value === 'string' || (Array.isArray(value) && value.every((v) => typeof v === 'string'))) {
+          slots[key] = value
+        } else {
+          problems.push(`槽位 ${key} 须为 string 或 string 数组`)
+        }
+      }
+      patch.slots = slots
+    }
+  }
+  if (body.budgets !== undefined) {
+    if (typeof body.budgets !== 'object' || body.budgets === null || Array.isArray(body.budgets)) {
+      problems.push('budgets 须为对象')
+    } else {
+      const budgets = {}
+      for (const [key, value] of Object.entries(body.budgets)) {
+        if (!BUDGET_KEYS.includes(key)) {
+          problems.push(`未知预算键:${key}`)
+          continue
+        }
+        if (typeof value !== 'number' || !Number.isInteger(value)) {
+          problems.push(`预算 ${key} 须为整数`)
+          continue
+        }
+        budgets[key] = Math.max(1, Math.min(10, value))
+      }
+      patch.budgets = budgets
+    }
+  }
+  if (problems.length > 0) {
+    const err = new Error(problems.join(';'))
+    err.errors = problems
+    throw err
+  }
+  return patch
+}
+
+// ── 运行时控制(v5) ─────────────────────────────────────────────────────────
+const CONTROL_KINDS = ['message', 'cancel', 'pause', 'resume', 'approve', 'reject']
+const VERDICT_KINDS = new Set(['approve', 'reject'])
+const CONTROL_BY = new Set(['user', 'main-agent'])
+
+// 活跃判定:注册表在册或记录未终态(waiting_approval 属活跃)
+const isRunActive = (runId, record) => registry.drivers.has(runId) || (record && ACTIVE_STATES.has(record.status))
+
+export function handleControl(body) {
+  const runId = typeof body.runId === 'string' ? body.runId : ''
+  const kind = typeof body.kind === 'string' ? body.kind : ''
+  const store = reportStore()
+  if (!CONTROL_KINDS.includes(kind)) throw new Error('kind 须为 ' + CONTROL_KINDS.join('|'))
+  if (kind === 'message') {
+    if (typeof body.text !== 'string' || body.text.trim() === '') throw new Error('message 须携带非空 text')
+    const accepted = post(runId, { kind: 'message', text: body.text, inject: body.inject === true })
+    return { ok: accepted }
+  }
+  if (VERDICT_KINDS.has(kind)) {
+    // 外部裁决通道:by 必填(user|main-agent),代审(main-agent)须给出非空 reason
+    if (!CONTROL_BY.has(body.by)) throw new Error('裁决须携带 by(user|main-agent)')
+    if (body.by === 'main-agent' && (typeof body.reason !== 'string' || body.reason.trim() === '')) throw new Error('代审(main-agent)须携带非空 reason')
+    const accepted = post(runId, { kind, by: body.by, reason: typeof body.reason === 'string' ? body.reason : '' })
+    if (!accepted) return { ok: false }
+    // 裁决翻状态不推进:无活跃段时经会话挂靠拉下一段(页签先裁场景主循环无通知,须代为唤醒)
+    const record = store.get(runId)
+    const resumed = resumerOf(record?.sessionId)?.(runId) === true
+    return { ok: true, resumed }
+  }
+  const driver = registry.drivers.get(runId)
+  if (!driver) return { ok: false }
+  if (kind === 'cancel') {
+    store.step({ runId, event: 'control', body: { kind: 'cancel', by: 'user' } })
+    driver.cancel()
+  }
+  if (kind === 'pause') {
+    store.step({ runId, event: 'control', body: { kind: 'pause', by: 'user' } })
+    driver.pause()
+  }
+  if (kind === 'resume') {
+    // 仅 paused 受理;其余状态回状态不符(先到先得口径)
+    const accepted = driver.tabResume()
+    if (!accepted) return { ok: false, error: '状态不符:resume 仅受理 paused' }
+  }
+  return { ok: true }
+}
+
+export function registerBoardRoutes(ctx) {
+  const store = reportStore()
+  ctx.inject(['webServer'], (wctx) => {
+    const route = (path, handler, name) => wctx.effect(() => wctx.webServer.register({ kind: 'exact', path, handler }), name)
+    route('/api/rsww/runs', guardedRoute(async (req, res) => {
+      sendJson(res, 200, { runs: store.list() })
+    }), 'rsww runs route')
+    route('/api/rsww/run', guardedRoute(async (req, res) => {
+      const url = new URL(req.url, 'http://localhost')
+      const runId = url.searchParams.get('id') || ''
+      const run = store.get(runId)
+      if (!run) throw new Error('运行记录不存在:' + runId)
+      sendJson(res, 200, run)
+    }), 'rsww run detail route')
+    route('/api/rsww/control', guardedRoute.post(async (req, res) => {
+      const body = JSON.parse(await readJsonBody(req))
+      sendJson(res, 200, handleControl(body ?? {}))
+    }), 'rsww control route')
+    route('/api/rsww/resume-from', guardedRoute.post(async (req, res) => {
+      const body = JSON.parse(await readJsonBody(req))
+      const runId = typeof body.runId === 'string' ? body.runId : ''
+      const record = store.get(runId)
+      if (!record) throw new Error('运行记录不存在:' + runId)
+      if (isRunActive(runId, record)) throw new Error('运行进行中,不可续跑')
+      // 挂靠守卫:新 run 由原会话的推进器(orchestrator 行注册的 initiator)重建,engine/parent 闭包在其域内
+      const start = initiatorOf(record.sessionId)
+      if (!start) throw new Error('请先打开对应模式会话再重跑')
+      const fromStepId = typeof body.fromStepId === 'string' && body.fromStepId !== '' ? body.fromStepId : undefined
+      // 非法 fromStepId 显式报错(不静默退化为纯断点续跑)
+      if (fromStepId !== undefined && record.plan?.steps?.some((p) => p.ref === fromStepId) !== true) {
+        throw new Error('fromStepId 不在剧本中:' + fromStepId)
+      }
+      const inputs = body.inputs && typeof body.inputs === 'object' ? body.inputs : undefined
+      const outcome = start(record, fromStepId, inputs)
+      if (!outcome.ok) throw new Error(outcome.error)
+      // 纠偏消息不跨 run:旧 run 受理未消费的纠偏不带入种子(controls 属旧 run 审计)
+      sendJson(res, 200, { ok: true, runId: outcome.runId, hint: '旧 run 未消费的纠偏消息不带入新 run' })
+    }), 'rsww resume-from route')
+    route('/api/rsww/run-remove', guardedRoute.post(async (req, res) => {
+      const body = JSON.parse(await readJsonBody(req))
+      const runId = typeof body.runId === 'string' ? body.runId : ''
+      const record = store.has(runId) ? store.get(runId) : undefined
+      if (record && isRunActive(runId, record)) throw new Error('运行进行中,不可删除')
+      store.remove(runId)
+      sendJson(res, 200, { ok: true })
+    }), 'rsww run-remove route')
+    route('/api/rsww/templates', guardedRoute(async (req, res) => {
+      sendJson(res, 200, { templates: readTemplates() })
+    }), 'rsww templates route')
+    route('/api/rsww/template', guardedRoute(async (req, res) => {
+      const url = new URL(req.url, 'http://localhost')
+      const id = url.searchParams.get('id') || ''
+      const entry = readTemplates().find((t) => t.id === id)
+      if (!entry) throw new Error('模板不存在:' + id)
+      let parsed
+      try {
+        parsed = JSON.parse(entry.json)
+      } catch (e) {
+        throw new Error('模板文本解析失败:' + e.message)
+      }
+      sendJson(res, 200, { entry, parsed })
+    }), 'rsww template detail route')
+    route('/api/rsww/released', guardedRoute(async (req, res) => {
+      sendJson(res, 200, { ids: releasedTemplateIds() })
+    }), 'rsww released route')
+    route('/api/rsww/spec', guardedRoute(async (req, res) => {
+      sendJson(res, 200, { spec: SPEC_TEXT })
+    }), 'rsww spec route')
+    route('/api/rsww/template-save', guardedRoute.post(async (req, res) => {
+      const body = JSON.parse(await readJsonBody(req))
+      const id = typeof body.id === 'string' ? body.id.trim() : ''
+      const { parsed, json } = parseTemplateEntry(id, body)
+      if (body.dryRun === true) {
+        sendJson(res, 200, { ok: true, dryRun: true })
+        return
+      }
+      const templates = rawTemplates().filter((t) => t.id !== id)
+      templates.push({
+        id,
+        label: typeof body.label === 'string' && body.label.trim() !== '' ? body.label.trim() : parsed.label || id,
+        description: typeof body.description === 'string' && body.description.trim() !== '' ? body.description.trim() : parsed.description || '',
+        enabled: body.enabled !== false,
+        json,
+      })
+      writeTemplates(templates)
+      sendJson(res, 200, { ok: true })
+    }), 'rsww template-save route')
+    route('/api/rsww/template-remove', guardedRoute.post(async (req, res) => {
+      const body = JSON.parse(await readJsonBody(req))
+      const id = typeof body.id === 'string' ? body.id.trim() : ''
+      const outcome = removeTemplateById(id)
+      if (!outcome.ok) throw new Error(outcome.error)
+      sendJson(res, 200, { ok: true })
+    }), 'rsww template-remove route')
+    route('/api/rsww/release', guardedRoute.post(async (req, res) => {
+      const body = JSON.parse(await readJsonBody(req))
+      const id = typeof body.id === 'string' ? body.id.trim() : ''
+      const entries = readTemplates()
+      const entry = entries.find((t) => t.id === id)
+      if (!entry) throw new Error('模板不存在:' + id)
+      if (entry.enabled === false) throw new Error('模板已禁用,不可释放:' + id)
+      // 跨流程校验(spec §9):flow 引用存在性+环/深度在释放权威点执行
+      const parsedSet = entries.map((t) => {
+        try { return JSON.parse(t.json) } catch { return null }
+      }).filter((t) => t !== null)
+      const setErrors = validateTemplateSet(parsedSet).filter((e) => e.target === 'top:id' && e.message.startsWith(id + ' '))
+      if (setErrors.length > 0) throw new Error('模板集合校验失败:' + setErrors.map((e) => e.message).join(';'))
+      const outcome = releaseFlowTemplate(entry)
+      sendJson(res, 200, { ok: true, outcome })
+    }), 'rsww release route')
+    route('/api/rsww/unrelease', guardedRoute.post(async (req, res) => {
+      const body = JSON.parse(await readJsonBody(req))
+      const id = typeof body.id === 'string' ? body.id.trim() : ''
+      const outcome = unreleaseFlowTemplate(id)
+      sendJson(res, 200, { ok: true, outcome })
+    }), 'rsww unrelease route')
+    route('/api/rsww/config', guardedRoute(async (req, res) => {
+      sendJson(res, 200, { config: normalizeConfig(loadJson('config.json', undefined)) })
+    }), 'rsww config route')
+    route('/api/rsww/config-save', guardedRoute.post(async (req, res) => {
+      const body = JSON.parse(await readJsonBody(req))
+      const patch = configSavePatch(body ?? {})
+      const current = normalizeConfig(loadJson('config.json', undefined))
+      // config.json 权威节集 = slots/budgets(data-design);templates 属 templates.json 独立存储
+      const { templates: _drop, ...persistable } = current
+      saveJson('config.json', { ...persistable, ...patch })
+      sendJson(res, 200, { ok: true })
+    }), 'rsww config-save route')
+  })
+}

package/lib/driver/approve.mjs

@@ -0,0 +1,126 @@
+// 审批裁决路由:重做循环/耗尽清算/升级账本 + 外部裁决(waiting_approval 置位/裁决回写/来源入账)
+const resetStepForRedo = (s) => {
+  s.status = 'pending'
+  s.outputs = null
+  s.failCount = 0
+  s.instances = []
+}
+
+// target 及其未完成下游集合(剧本依赖图的可达闭包,不含 escalate-only)
+function descendantsOf(script, targetId) {
+  const { depsById, escalateOnly } = script
+  const children = new Map()
+  for (const [id, ds] of depsById) {
+    for (const d of ds) {
+      if (!children.has(d)) children.set(d, [])
+      children.get(d).push(id)
+    }
+  }
+  const out = new Set()
+  const walk = (id) => {
+    for (const child of children.get(id) ?? []) {
+      if (out.has(child) || escalateOnly.has(child)) continue
+      out.add(child)
+      walk(child)
+    }
+  }
+  walk(targetId)
+  return out
+}
+
+// 审批结果路由;返回 {verdict, exhausted, routedTo}。result = { outputs: { verdict, comments } }(外部裁决包成同形)
+export function applyApproveResult(state, script, approveStep, result, budgets) {
+  const s = state.steps[approveStep.id]
+  const verdict = result.outputs?.verdict
+  state.approvals[approveStep.id] ??= { rounds: 0 }
+  const ledger = state.approvals[approveStep.id]
+  ledger.lastComments = result.outputs?.comments ?? ''
+
+  if (verdict === 'APPROVED') {
+    s.status = 'done'
+    s.outputs = result.outputs
+    return { verdict: 'APPROVED', exhausted: false }
+  }
+
+  // REJECTED
+  ledger.rounds++
+  const limit = approveStep.rounds ?? budgets.approveRounds
+  const target = state.steps[approveStep.target]
+  if (ledger.rounds < limit) {
+    const prevOutputs = target?.outputs
+    s.status = 'pending'
+    s.outputs = null
+    if (target) {
+      target.redoBy = approveStep.id
+      resetStepForRedo(target)
+      // 全部后代重置(target 产出改变,done 后代亦陈旧)
+      for (const id of descendantsOf(script, approveStep.target)) {
+        resetStepForRedo(state.steps[id])
+      }
+    }
+    return { verdict: 'REJECTED', exhausted: false, redoTarget: approveStep.target, comments: result.outputs?.comments, prevOutputs: prevOutputs ? JSON.stringify(prevOutputs, null, 2) : null }
+  }
+
+  // 耗尽
+  s.status = 'done'
+  s.outputs = result.outputs
+  s.verdictExhausted = true
+  if (approveStep.onExhausted === 'blocked' || approveStep.onExhausted === undefined) {
+    // 缺省 blocked(spec §4 口径,与客户端提示一致):无出口即终止
+    state.terminalBlocked = `审批轮次耗尽:${approveStep.label ?? approveStep.id}(target=${approveStep.target},rounds=${ledger.rounds})`
+    return { verdict: 'REJECTED', exhausted: true, routedTo: 'blocked' }
+  }
+  const escalateId = approveStep.onExhausted
+  const escalateStep = state.steps[escalateId]
+  state.escalations++
+  if (target) {
+    target.status = 'skipped'
+    target.skipReason = '审批耗尽走升级出口'
+    target.outputs = null
+    for (const id of descendantsOf(script, approveStep.target)) {
+      const ds = state.steps[id]
+      if (!ds || ds.status === 'done') continue
+      ds.status = 'skipped'
+      ds.skipReason = '审批耗尽走升级出口'
+      ds.outputs = null
+      ds.instances = []
+    }
+  }
+  if (escalateStep) escalateStep.escalateReady = true
+  const hitLimit = state.escalations >= (budgets.escalateLimit ?? 2)
+  if (hitLimit) {
+    state.escalateLimitReached = true
+    state.terminalBlocked = `升级账达上限(${state.escalations}),整流程 blocked`
+  }
+  return { verdict: 'REJECTED', exhausted: true, routedTo: escalateId, escalateLimitReached: hitLimit }
+}
+
+// 外部裁决回写(waiting_approval 期间);paused 期间的裁决由 driver 入队,resume 段首生效
+// 返回 { applied: true, route } | { applied: false }
+export function applyExternalVerdict(state, script, approveStep, { verdict, comments }, budgets = {}) {
+  if (state.status !== 'waiting_approval') return { applied: false }
+  const route = applyApproveResult(state, script, approveStep, { outputs: { verdict, comments } }, budgets)
+  // blocked 终态由下一段 terminal 侦测收口;此处仅翻回 running(下一段推进/收口)
+  state.status = 'running'
+  return { applied: true, route }
+}
+
+// 段 settle 负载(waiting):待裁决摘要 + 口径上下文(feat/approve-bridge.md 字段集)
+export function waitingPayload({ runId, state, script, planStepOf, approveStep }) {
+  const target = state.steps[approveStep.target]
+  const planStep = planStepOf.get(approveStep.id)
+  const brief = planStep?.done || planStep?.note || approveStep.prompt
+  const ledger = state.approvals[approveStep.id]
+  return {
+    kind: 'waiting',
+    runId,
+    status: state.status,
+    waiting: {
+      stepId: approveStep.id,
+      target: { id: approveStep.target, label: approveStep.target, outputs: target?.outputs ?? null },
+      brief,
+      comments: ledger?.lastComments ?? '',
+      rounds: ledger?.rounds ?? 0,
+    },
+  }
+}

package/lib/driver/control.mjs

@@ -0,0 +1,46 @@
+// 控制平面注册表:cancel/resume 即时通道直调 RunDriver;message 经 driver 落账(队列单例不持有 store)
+export const registry = {
+  drivers: new Map(),
+  initiators: new Map(),
+  resumers: new Map(),
+}
+
+export function registerDriver(runId, driver) {
+  registry.drivers.set(runId, driver)
+}
+
+export function unregisterDriver(runId) {
+  registry.drivers.delete(runId)
+}
+
+export function registerInitiator(sessionId, start) {
+  registry.initiators.set(sessionId, start)
+}
+
+export function unregisterInitiator(sessionId) {
+  registry.initiators.delete(sessionId)
+}
+
+export function initiatorOf(sessionId) {
+  return registry.initiators.get(sessionId)
+}
+
+// 段拉起挂靠:页签裁决受理后经此回到 orchestrator 域拉下一段(裁决翻状态不推进,推进责任仍在段 job)
+export function registerResumer(sessionId, resume) {
+  registry.resumers.set(sessionId, resume)
+}
+
+export function unregisterResumer(sessionId) {
+  registry.resumers.delete(sessionId)
+}
+
+export function resumerOf(sessionId) {
+  return registry.resumers.get(sessionId)
+}
+
+// post 受理语义:活跃(未终态且已注册 driver)才受理;落账经 driver 自持 store
+export function post(runId, event) {
+  const driver = registry.drivers.get(runId)
+  if (!driver) return false
+  return driver.handlePost(event)
+}