@mzzsfy/dsh-rs-workflow 1.0.1 → 1.1.0

package/README.md

@@ -25,4 +25,4 @@ node --test "test/*.test.mjs"      # 包内测试(在 packages/dsh-rs-workflow
 
 ## dsh 版本兼容
 
-三版本全部通过:preset 释放、Agent 预设页若水工作流卡、rs_workflow_ 工具可列出、激活 live。
+三版本(0.1.2-rc.1 / 0.1.5-rc.3 / 0.1.7-rc.1)全部通过:preset 释放、Agent 预设页若水工作流卡(0.1.7-rc.1 预设页换形「模式」卡,属宿主演进)、rs_workflow_ 工具可列出、配置页六工作位、移除删除联动、激活 live。

package/lib/board.mjs

@@ -1,10 +1,22 @@
 // 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)
+// 安全边界(全仓库约定,AGENTS.md):不做 host 认证,无 Host 白名单/rebinding 防线/token 校验;
+// 认证由宿主原生 cookie/startup-auth 承担,写路由跨源防护以 Origin 同源比对为上限
 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 { releasedTemplateIds } from './release.mjs'
+import {
+  currentAgentPresets,
+  disposeAllRegistered,
+  markReleased,
+  registryFormAvailable,
+  replayReleased,
+  setAgentPresets,
+  unreleaseTemplateVia,
+  releaseTemplateVia,
+} from './release-registry.mjs'
 import { SPEC_TEXT } from './spec.mjs'
 import { normalizeConfig, BUDGET_KEYS, SLOT_KEYS } from './settings-schema.mjs'
 import { loadJson, saveJson } from './storage.mjs'
@@ -67,21 +79,26 @@ guardedRoute.post = (handler) => async (req, res) => {
   return guardedRoute(handler)(req, res)
 }
 
-function readJsonBody(req) {
+function readJsonBody(req, res) {
   return new Promise((resolve, reject) => {
     let size = 0
     const chunks = []
+    let over = false
     req.on('data', (chunk) => {
       size += chunk.length
       if (size > BODY_MAX_BYTES) {
+        // 只暂停流入并标记超限,不销毁 socket:连接毁了 guardedRoute 的 400 就送不出去
+        over = true
+        req.pause()
         reject(new Error('请求体超过上限'))
-        req.destroy()
         return
       }
-      chunks.push(chunk)
+      if (!over) chunks.push(chunk)
     })
-    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')))
-    req.on('error', reject)
+    req.on('end', () => { if (!over) resolve(Buffer.concat(chunks).toString('utf8')) })
+    req.on('error', () => { if (!over) reject(new Error('请求体读取失败')) })
+    // 超限后 end 不再流到(已暂停):挂 res 收尾销毁,防 socket 悬挂
+    res.on('finish', () => req.destroy())
   })
 }
 
@@ -98,13 +115,25 @@ function writeTemplates(templates) {
   saveJson('templates.json', templates)
 }
 
-function removeTemplateById(id) {
+// ── 释放分派(注册形态 rc.1+ / 目录形态 0.1.2-0.1.5,见 计划-rs-workflow-preset-rc1.md)──
+// released 事实源随形态:注册形态 = templates.json released 标志(markReleased 落盘);
+// 目录形态 = 目录本身。服务当值经 release-registry 模块单例,template-tool 行同源消费
+const releaseDispatch = (entry) => releaseTemplateVia(currentAgentPresets(), entry)
+
+const unreleaseDispatch = (id) => unreleaseTemplateVia(currentAgentPresets(), id)
+
+function releasedIdsVia() {
+  if (!registryFormAvailable(currentAgentPresets())) return releasedTemplateIds()
+  return rawTemplates().filter((t) => t.released === true).map((t) => t.id)
+}
+
+async 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)
+  // 撤下释放物:注册形态注销预设,目录形态移除释放目录(外来目录返回 foreign 不动)
+  const outcome = await unreleaseDispatch(id)
   return { ok: true, outcome }
 }
 
@@ -225,6 +254,19 @@ export function handleControl(body) {
 
 export function registerBoardRoutes(ctx) {
   const store = reportStore()
+  // 注册形态运行态:服务注入即设当值 + 重放已释放模板;行卸载清当值并注销全部
+  // 注册(热重载后随重放重建)。目录形态宿主(无 register)保持当值空缺
+  ctx.inject(['agentPresets'], (actx) => {
+    const service = actx.agentPresets
+    if (!registryFormAvailable(service)) return
+    setAgentPresets(service)
+    const released = rawTemplates().filter((t) => t.released === true && t.enabled !== false)
+    replayReleased(service, released).catch(() => {})
+    actx.effect(() => async () => {
+      setAgentPresets(undefined)
+      await disposeAllRegistered()
+    }, 'rs-workflow preset registrations')
+  })
   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) => {
@@ -238,11 +280,11 @@ export function registerBoardRoutes(ctx) {
       sendJson(res, 200, run)
     }), 'rsww run detail route')
     route('/api/rsww/control', guardedRoute.post(async (req, res) => {
-      const body = JSON.parse(await readJsonBody(req))
+      const body = JSON.parse(await readJsonBody(req, res))
       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 body = JSON.parse(await readJsonBody(req, res))
       const runId = typeof body.runId === 'string' ? body.runId : ''
       const record = store.get(runId)
       if (!record) throw new Error('运行记录不存在:' + runId)
@@ -255,14 +297,21 @@ export function registerBoardRoutes(ctx) {
       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
+      // inputs 须为字符串值对象:数组/嵌套值在种子展开中失真
+      let inputs
+      if (body.inputs !== undefined && body.inputs !== null) {
+        if (typeof body.inputs !== 'object' || Array.isArray(body.inputs) || Object.values(body.inputs).some((v) => typeof v !== 'string')) {
+          throw new Error('inputs 必须为字符串值对象(键→字符串)')
+        }
+        inputs = body.inputs
+      }
       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 body = JSON.parse(await readJsonBody(req, res))
       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('运行进行中,不可删除')
@@ -286,19 +335,20 @@ export function registerBoardRoutes(ctx) {
       sendJson(res, 200, { entry, parsed })
     }), 'rsww template detail route')
     route('/api/rsww/released', guardedRoute(async (req, res) => {
-      sendJson(res, 200, { ids: releasedTemplateIds() })
+      sendJson(res, 200, { ids: releasedIdsVia() })
     }), '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 body = JSON.parse(await readJsonBody(req, res))
       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 previous = rawTemplates().find((t) => t.id === id)
       const templates = rawTemplates().filter((t) => t.id !== id)
       templates.push({
         id,
@@ -306,19 +356,21 @@ export function registerBoardRoutes(ctx) {
         description: typeof body.description === 'string' && body.description.trim() !== '' ? body.description.trim() : parsed.description || '',
         enabled: body.enabled !== false,
         json,
+        // 已释放模板的编辑性重存不改变释放态(注销走 unrelease 显式动作)
+        ...(previous?.released === true ? { released: true } : {}),
       })
       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 body = JSON.parse(await readJsonBody(req, res))
       const id = typeof body.id === 'string' ? body.id.trim() : ''
-      const outcome = removeTemplateById(id)
+      const outcome = await 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 body = JSON.parse(await readJsonBody(req, res))
       const id = typeof body.id === 'string' ? body.id.trim() : ''
       const entries = readTemplates()
       const entry = entries.find((t) => t.id === id)
@@ -330,20 +382,23 @@ export function registerBoardRoutes(ctx) {
       }).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 })
+      const result = await releaseDispatch(entry)
+      if (result.outcome === 'failed') throw new Error(result.broken ?? '释放失败')
+      markReleased(id, true)
+      sendJson(res, 200, { ok: true, outcome: result.outcome, ...(result.broken === undefined ? {} : { broken: result.broken }) })
     }), 'rsww release route')
     route('/api/rsww/unrelease', guardedRoute.post(async (req, res) => {
-      const body = JSON.parse(await readJsonBody(req))
+      const body = JSON.parse(await readJsonBody(req, res))
       const id = typeof body.id === 'string' ? body.id.trim() : ''
-      const outcome = unreleaseFlowTemplate(id)
-      sendJson(res, 200, { ok: true, outcome })
+      const result = await unreleaseDispatch(id)
+      markReleased(id, false)
+      sendJson(res, 200, { ok: true, outcome: result.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 body = JSON.parse(await readJsonBody(req, res))
       const patch = configSavePatch(body ?? {})
       const current = normalizeConfig(loadJson('config.json', undefined))
       // config.json 权威节集 = slots/budgets(data-design);templates 属 templates.json 独立存储

package/lib/driver/approve.mjs

@@ -106,7 +106,7 @@ export function applyExternalVerdict(state, script, approveStep, { verdict, comm
 }
 
 // 段 settle 负载(waiting):待裁决摘要 + 口径上下文(feat/approve-bridge.md 字段集)
-export function waitingPayload({ runId, state, script, planStepOf, approveStep }) {
+export function waitingPayload({ runId, state, script, planStepOf, approveStep, autoApprove = false }) {
   const target = state.steps[approveStep.target]
   const planStep = planStepOf.get(approveStep.id)
   const brief = planStep?.done || planStep?.note || approveStep.prompt
@@ -121,6 +121,8 @@ export function waitingPayload({ runId, state, script, planStepOf, approveStep }
       brief,
       comments: ledger?.lastComments ?? '',
       rounds: ledger?.rounds ?? 0,
+      // 模板代审口径:主循环 persona 据此决定代审(by 缺省)或转呈真人(by=user)
+      autoApprove,
     },
   }
 }

package/lib/driver/index.mjs

@@ -1,5 +1,7 @@
 // RunDriver 聚合(v5):剧本驱动;runSegment 分段推进(审批到达/暂停/终态即返回 settle 负载);
 // 外部裁决回写(waiting_approval 即时应用,paused 入队 resume 生效);取消优先;推进责任在主循环 resume
+import { readFileSync } from 'node:fs'
+import { isAbsolute, join, resolve, sep } from 'node:path'
 import { reportStore } from '../store.mjs'
 import { templateDeps } from '../planner-gate.mjs'
 import { nextBatch, scriptViewOf } from './scheduler.mjs'
@@ -88,11 +90,13 @@ export function buildSeed(record, plan, fromStepId, inputs) {
     }
   }
   state.pendingApprovals = []
-  // 终态污染标志清零:续跑后旧账不得再次收口(blocked)或无耗尽即派发升级步
+  // 终态污染标志清零:续跑后旧账不得再次收口(blocked)或无耗尽即派发升级步;
+  // escalateReady 是步级标记(scheduler 消费),须逐步清零
   state.terminalBlocked = false
-  state.escalateReady = []
   state.escalateLimitReached = false
-  state.controlSeq = record.controls?.length ?? 0
+  for (const s of Object.values(state.steps)) s.escalateReady = false
+  // 控制序号对齐新记录:续跑生成全新 store 记录(controls 从空起),沿用旧计数会吞掉新记录前缀消息
+  state.controlSeq = 0
   return state
 }
 
@@ -123,27 +127,46 @@ export class RunDriver {
     this.subordinate = subordinate
     // 编排子代理的挂载父 agent(与 workflow 工具链对齐;undefined 时引擎派发行为未定义)
     this.parent = parent
+    // spec §8 doc:<相对路径>:读会话工作区文件,缺失不阻断(空串);resolve 限定在 workspace 内防路径逃逸
+    const base = resolve(workspace || process.cwd())
+    this.readDoc = (rel) => {
+      const target = resolve(base, rel)
+      if (!target.startsWith(base + sep) && target !== base) return ''
+      try { return readFileSync(target, 'utf8') } catch { return '' }
+    }
   }
 
   // 段推进唯一入口:跑到下一个段边界(审批到达/暂停/终态)返回 settle 负载;orchestrator 包装为 continuable job
   async runSegment() {
+    // 重入防护:在飞段由 settlePromise 承载(取消方 await 它收敛,而非重入第二个 loop)
+    if (this.active) return this.settlePromise ?? this.terminalPayload()
     if (this.finished || TERMINAL_STATES.has(this.state.status)) {
       return this.terminalPayload()
     }
     this.active = true
-    try {
-      this.drainPendingApprovals()
-      return await this.loop()
-    } catch (e) {
-      if (this.signal.aborted) {
-        this.finish('cancelled', CANCELLED_SUMMARY)
+    this.settlePromise = (async () => {
+      try {
+        this.drainPendingApprovals()
+        return await this.loop()
+      } catch (e) {
+        if (this.signal.aborted) {
+          this.finish('cancelled', CANCELLED_SUMMARY)
+          return this.terminalPayload()
+        }
+        this.finish('failed', `驱动器异常:${e?.message ?? e}`)
         return this.terminalPayload()
+      } finally {
+        this.active = false
+        this.settlePromise = undefined
       }
-      this.finish('failed', `驱动器异常:${e?.message ?? e}`)
-      return this.terminalPayload()
-    } finally {
-      this.active = false
-    }
+    })()
+    return this.settlePromise
+  }
+
+  /** 取消并等待在飞段收敛(无在飞段时即时收敛) */
+  async cancelAndSettle() {
+    this.cancel()
+    if (this.settlePromise !== undefined) await this.settlePromise.catch(() => {})
   }
 
   startPersist() {
@@ -159,6 +182,8 @@ export class RunDriver {
     if (this.finished || TERMINAL_STATES.has(this.state.status)) return
     // 统一转 paused(与 waiting_approval 互斥,paused 优先);活跃段在飞批次收敛后于段顶 settle
     this.state.status = 'paused'
+    // 暂停即撤销先前的恢复意图,否则陈旧标记会让守门持续催 resume
+    this.awaitingResume = false
     this.persistState()
   }
 
@@ -243,6 +268,8 @@ export class RunDriver {
         this.state.redoInfo = { [route.redoTarget]: { comments: route.comments, prevOutputs: route.prevOutputs } }
       }
     }
+    // 与 waiting 直裁路径同款收口:残留 waitingApproval 会让后续 pause 期裁决对非等待步幽灵生效
+    this.state.waitingApproval = undefined
     this.store.update({ runId: this.runId, waiting: null })
   }
 
@@ -266,6 +293,9 @@ export class RunDriver {
   }
 
   persistState() {
+    // 嵌套子流程与父共享同 runId 记录:子状态落盘会覆盖父的全局 state,崩溃后续跑种子即失真;
+    // 子流程中间态不落盘,flow 步结束后由父 persistState 兜底
+    if (this.subordinate) return
     this.store.update({ runId: this.runId, state: this.state, status: this.state.status })
   }
 
@@ -343,8 +373,10 @@ export class RunDriver {
         const step = batch.step
         this.state.status = 'waiting_approval'
         this.state.waitingApproval = step.id
+        // 模板代审口径落 state:进程重启后 status 工具仍可透出
+        this.state.waitingAutoApprove = this.template?.autoApprove === true
         this.persistState()
-        const payload = waitingPayload({ runId: this.runId, state: this.state, script: this.script, planStepOf: this.planStepOf, approveStep: step })
+        const payload = waitingPayload({ runId: this.runId, state: this.state, script: this.script, planStepOf: this.planStepOf, approveStep: step, autoApprove: this.template?.autoApprove === true })
         // 待裁决摘要落盘:页签 /run 路由据此渲染审批上下文
         this.store.update({ runId: this.runId, waiting: payload.waiting })
         return payload

package/lib/driver/runner.mjs

@@ -48,7 +48,7 @@ function rotateCursor(state, slotKey) {
   state.slotCursor[slotKey] = (state.slotCursor[slotKey] ?? 0) + 1
 }
 
-// 单批次:组 Batch → engine.start → 收敛逐 call 记账。返回 {results, cancelled}
+// 单批次:组 Batch → engine.start → 收敛逐 call 记账。返回 {settled, cancelled}
 export async function runBatch({ state, script, template, batch, ctx }) {
   const { store, runId, engine, parent, signal } = ctx
   const calls = []
@@ -87,8 +87,9 @@ export async function runBatch({ state, script, template, batch, ctx }) {
   }
 
   let outcome
+  let run
   try {
-    const run = engine.start({
+    run = engine.start({
       script: FLOW_EXEC_SOURCE,
       args: { calls },
       // 宿主 meta 契约:description 必填非空;phases 必须为 {title} 对象数组(dsh-workflow-worker-thread meta 校验)
@@ -104,15 +105,20 @@ export async function runBatch({ state, script, template, batch, ctx }) {
   } catch (e) {
     if (signal?.aborted) return { cancelled: true }
     outcome = { results: calls.map((c) => ({ callId: c.callId, ok: false, error: String(e?.message ?? e) })) }
+  } finally {
+    // 宿主契约:caller must dispose every run(否则 worker 线程泄漏);engine.start 同步抛时 run 为空
+    await run?.dispose?.().catch?.(() => {})
   }
   if (signal?.aborted) return { cancelled: true }
   // 引擎 run.result 契约:{ value(脚本返回值), stopReason, error?, agentsStarted }
-  // stopReason 非 completed(如 cancelled/error)时 value 不可信,全部调用按失败记账
+  // stopReason 非 completed(如 error)时 value 不可信,全部调用统一按失败记账
+  let results
   if (outcome?.stopReason !== undefined && outcome?.stopReason !== 'completed') {
     const reason = String(outcome?.error ?? outcome?.stopReason)
-    return { results: calls.map((c) => ({ callId: c.callId, ok: false, error: reason })) }
+    results = calls.map((c) => ({ callId: c.callId, ok: false, error: reason }))
+  } else {
+    results = outcome?.value?.results ?? outcome?.results ?? []
   }
-  const results = outcome?.value?.results ?? outcome?.results ?? []
   const settled = []
   for (const result of results) {
     const meta = callMeta.get(result.callId)

package/lib/driver/scheduler.mjs

@@ -45,7 +45,8 @@ function expandForEach(state, step) {
   const list = sourceList(state, step)
   if (list === null) return
   s.instances = list.map((item, index) => ({
-    key: `#${index + 1}`, index, item, status: 'pending', outputs: null, failCount: 0, carry: null,
+    // index 1 基(与 key #N 及 spec {item.index} 序号口径一致)
+    key: `#${index + 1}`, index: index + 1, item, status: 'pending', outputs: null, failCount: 0, carry: null,
   }))
 }
 

package/lib/guard.mjs

@@ -0,0 +1,67 @@
+// 会话守门:轮次将停时判定本会话编排是否欠动作(persona 判据 3 的机器化执行)
+// 判据来源:running 且无活跃段 job → 欠 resume;paused 且 awaitingResume → 欠 resume;
+// waiting_approval → 欠裁决。终态与无现役 run 不拦。
+// 拦截手段由调用方承担(agent.steer 投喂提醒消息,机器重读 inbox 后继续跑)。
+
+// 单个欠动作周期的提醒上限:弱模型可能忽略首次提醒,但无限提醒会烧 token 死循环。
+// 计数在轮次不欠动作时清零,故多步编排的每个欠动作周期各自享有上限,而非全 run 共享。
+export const MAX_NUDGE = 2
+
+const ACTION_OF_STATUS = {
+  waiting_approval: { need: '裁决', text: '等待裁决' },
+  paused: { need: 'resume', text: '已暂停' },
+}
+
+/** 判据:record 状态 + driver 活跃度 → 是否欠动作;无现役 run / 终态 / 段在飞均返回 undefined */
+export function pendingOf(record, driver) {
+  if (record === undefined) return undefined
+  if (record.status === 'running') {
+    // 段在飞即正常等待:段 job settle 会经完成通知唤醒主循环,此时轮次停是合理行为
+    return driver?.active === true ? undefined : { need: 'resume', text: '运行中待拉起' }
+  }
+  const known = ACTION_OF_STATUS[record.status]
+  if (known === undefined) return undefined
+  if (record.status === 'paused' && driver?.awaitingResume !== true) {
+    // paused 且页签未发恢复:裁决已入队的 resume 拉段仍欠——段首生效前欠动作不变
+    if ((record.state?.pendingApprovals?.length ?? 0) > 0) return { need: 'resume', text: '已暂停(待生效裁决)' }
+    return undefined
+  }
+  return known
+}
+
+/** 提醒计数闸:按欠动作周期独立计数,超上限返回 false(调用方改记告警,不再 steer) */
+export function createNudgeGate(maxNudge = MAX_NUDGE) {
+  const counts = new Map()
+  const warned = new Set()
+  return {
+    take(runId) {
+      const used = counts.get(runId) ?? 0
+      if (used >= maxNudge) return false
+      counts.set(runId, used + 1)
+      return true
+    },
+    clear(runId) {
+      counts.delete(runId)
+      warned.delete(runId)
+    },
+    used(runId) {
+      return counts.get(runId) ?? 0
+    },
+    /** 首次触顶返回 true,此后false(告警只一次;clear 重置) */
+    exhausted(runId) {
+      if ((counts.get(runId) ?? 0) < maxNudge) return false
+      if (warned.has(runId)) return false
+      warned.add(runId)
+      return true
+    },
+  }
+}
+
+/** 提醒文案:给出 runId / 状态 / 欠动作,并指向应调用的工具 */
+export function nudgeText(runId, pending) {
+  // waiting_approval 有合法终止路径(转呈真人后等输入),文案带豁免以免误伤已处置的轮次
+  const dispense = pending.need === '裁决'
+    ? '裁决按模板 autoApprove 决定代审或转呈真人;若已转呈真人并等待其输入,则本轮无需再动作,可直接结束轮次。'
+    : '欠 resume 调 rs_workflow_resume 补拉。'
+  return `[若水守门] 本会话编排 ${runId} 未终态(状态=${pending.text},欠动作=${pending.need})。请立即调用 rs_workflow_status 查看并按流程纪律处置:${dispense}处置完成后才可结束轮次。`
+}