cli-swarm 7.0.32 → 7.0.34

package/broker.mjs

@@ -25,6 +25,19 @@ const EVALUATION_SCHEMA = 'skill-automatic-evaluation/1.0'
 const IDENTIFIER_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/
 const REQUEST_SCHEMA_PATTERN = /^([A-Za-z0-9.-]+\.skill)\.request\/([0-9]+\.[0-9]+)$/
 const TRANSPORT_ERROR_CODE_PATTERN = /^[A-Z][A-Z0-9_]{1,63}$/
+const NETWORK_TRANSPORT_ERROR = 'NETWORK_TRANSPORT'
+const SKILL_INVOCATION_ERROR = 'SKILL_INVOCATION_FAILED'
+
+class OfficialSkillInvocationError extends Error {
+  constructor(context, operation, transportCode) {
+    super(`${context.displayName} ${operation} invocation failed: network transport ${transportCode}`)
+    this.name = 'OfficialSkillInvocationError'
+    this.code = NETWORK_TRANSPORT_ERROR
+    this.operation = operation
+    this.retryable = false
+    this.transportCode = transportCode
+  }
+}
 
 function asObject(value, label) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
@@ -237,6 +250,29 @@ export function transportFailureCode(error) {
   return 'UNKNOWN_TRANSPORT_ERROR'
 }
 
+export function officialSkillFailureResponse(error) {
+  if (error instanceof OfficialSkillInvocationError) {
+    return {
+      ok: false,
+      error: {
+        code: error.code,
+        message: error.message,
+        operation: error.operation,
+        retryable: error.retryable,
+        transportCode: error.transportCode,
+      },
+    }
+  }
+  return {
+    ok: false,
+    error: {
+      code: SKILL_INVOCATION_ERROR,
+      message: error instanceof Error ? error.message : 'Skill invocation failed',
+      retryable: false,
+    },
+  }
+}
+
 export async function invokeOfficialSkill(context, operation, input, dependencies) {
   const environment = asObject(dependencies.environment, 'broker environment')
   if (typeof dependencies.request !== 'function') {
@@ -253,9 +289,7 @@ export async function invokeOfficialSkill(context, operation, input, dependencie
       signal: AbortSignal.timeout(CALL_TIMEOUT_MS),
     })
   } catch (error) {
-    throw new Error(
-      `${context.displayName} ${operation} invocation failed: network transport ${transportFailureCode(error)}`,
-    )
+    throw new OfficialSkillInvocationError(context, operation, transportFailureCode(error))
   }
   const payload = await responsePayload(response, `${context.displayName} ${operation} response`)
   if (!response.ok || payload.ok !== true) {

package/installer.mjs

@@ -13,6 +13,7 @@ import {
   brokerCommandInput,
   invokeCommandInput,
   invokeOfficialSkill,
+  officialSkillFailureResponse,
 } from './broker.mjs'
 
 export {
@@ -25,6 +26,7 @@ export {
   callOfficialSkill,
   invokeCommandInput,
   invokeOfficialSkill,
+  officialSkillFailureResponse,
 } from './broker.mjs'
 
 const INSTALL_META = 'install-meta.json'
@@ -184,11 +186,19 @@ async function readBrokerSource(input) {
 }
 
 async function runBrokerInvocation(context, commandInput) {
-  const invocation = await invokeOfficialSkill(
-    context, commandInput.operation, commandInput.input, brokerDependencies(),
-  )
-  console.log(JSON.stringify(invocation))
-  return invocation
+  try {
+    const invocation = await invokeOfficialSkill(
+      context, commandInput.operation, commandInput.input, brokerDependencies(),
+    )
+    console.log(JSON.stringify(invocation))
+    return invocation
+  } catch (error) {
+    const response = officialSkillFailureResponse(error)
+    console.log(JSON.stringify({ response }))
+    console.error(response.error.message)
+    process.exitCode = 1
+    return null
+  }
 }
 
 export async function runIntakeHandshake(context, spec) {

package/package.json

@@ -17,6 +17,7 @@
     "skill/skill.json",
     "swarm-coordinator-fs.mjs",
     "swarm-coordinator-model.mjs",
+    "swarm-coordinator-waits.mjs",
     "swarm-coordinator.mjs",
     "swarm-runtime.mjs",
     "skill/references/org-chart.md",
@@ -33,5 +34,5 @@
     "url": "https://github.com/88208555/swarm-clitax.git"
   },
   "type": "module",
-  "version": "7.0.32"
+  "version": "7.0.34"
 }

package/skill/SKILL.md

@@ -5,7 +5,7 @@ description: '通过智能体大脑调度创建 N 个子智能体，用企业级
 
 # swarm
 
-Package version: v7.0.32
+Package version: v7.0.34
 
 把「项目需求」编排为一支可观测、可自治、可安全运转的智能体蜂群。
 

package/skill/references/autocoord.md

@@ -19,15 +19,41 @@
 - 构建/部署锁：同资源排队；申请前必须完成当前基线握手。
 - 基线握手：观察哈希必须等于任务卡基线，否则任务转为等待并返回重取清单。
 - 所有租约 TTL 最长 3600 秒；续期签发新租约，旧租约不再处于活动状态。
+- 锁 TTL 到期由协调扫描处理，锁释放事件可唤醒已声明该事件的依赖方。
+- `queueOnConflict=true` 必须显式提供正整数 `queueTimeoutMs`；它是排队时限，与授锁后的 `ttlSeconds` 独立。请求保存 queueId/deadlineAt；提升时持久保存该队列对应的原始 grant。恢复先执行一次 tick，再只读调用 `lock-queue-status`，输入 queueId/taskId/agentId/chainId；不重复申请锁。身份、资源、路径、当前租约或期限失配均拒绝，旧版已授锁但缺少关联记录也不会推测归属。
+- 队列到期后扫描记录 timed-out、向等待方写入 lock-denied 消息，并生成 need-human/Confirm 请求；宿主需呈现该请求。旧队列不再授锁，人工恢复任务后仍须提交带新明确时限的申请。旧版缺少 deadlineAt 的队列明确拒绝；不借用 eta 或租约 TTL。
+- 排队期间任务终止或原构建/部署基线握手改变，后续扫描将该请求明确标记 rejected。已授锁但释放、续期或到期后，原队列不能被用作新授权。
 
 ## 依赖等待
 
-等待前调用 `dependency-wait`，明确 `waiter`、`waitFor`、结构化 `event`、`expectedWithinMs`、到达/超时策略和 `refetchPaths`。活动等待会阻断同 chain 的 Aimlock 预算读取。
+等待前调用 `dependency-wait`，明确 `waiter`、`waitFor`、结构化 `event`、`expectedWithinMs`、到达/超时策略和 `refetchPaths`。活动等待及尚未完成的真人裁决必须阻断对应 chain 的受控工作，不能只发提醒后继续执行。
 
-- 事件到达：5 秒目标窗口内路由唤醒包，内容含事件与重取清单。
-- 对方失败或被回收：立即以 `dependency-terminated` 唤醒，不等超时。
-- 超时：按声明处置；`escalate-need-human` 和连续第二次超时返回 `status=blocked`、高风险 Confirm Protocol 请求与 `nextStep=confirm-protocol`。宿主必须先调用该请求并等待人类答案，不能把请求对象当作已确认。
-- 成环：登记时或 `tick` 检出后立即打断全部相关等待，并生成真人裁决请求。
-- 未登记等待：`task-status=waiting` 返回 `undeclaredWait=true` 和补登提示。
+宿主的等待流程：
 
-等待必须由事件到达、终止通知、超时处置或死锁打断结束，不允许无限期静默挂起。
+1. 调用 `dependency-wait` 登记具体事件依赖；使用其返回状态判断是否还需要等待。
+2. 需要继续等待时，宿主显式调用 `wait-for-event`。该本地调用驱动协调扫描，检查事件、任务终止、租约到期、依赖超时与死锁，并返回对应唤醒包或确认请求。
+3. 收到事件后消费唤醒包和重取清单；同一任务仍有其他活动依赖时，继续保持等待。
+4. 收到高风险确认请求时，先调用 Confirm Protocol，再由宿主呈现请求、取得真实用户答案并回传裁决。请求对象和唤醒通知本身都不授予执行权限。
+5. 主动放弃等待时调用 `wait-cancel`，更新指定等待及审计台账；不得仅停止本地等待进程或在聊天中宣布放弃。
+
+### 事件与处置
+
+- 事件到达：匹配等待并生成包含事件内容和重取清单的唤醒包；已在台账中的匹配事件应在登记等待时检查。
+- 任务完成：对应完成事件参与依赖路由。
+- 对方失败或被回收：立即产生终止通知；登记依赖时同样检查对方是否已经终止，不能等满超时才发现。
+- 超时：按声明处置；`escalate-need-human` 和连续第二次超时产生高风险 Confirm Protocol 请求。成功收到依赖事件后，连续超时计数应重新开始。
+- 成环：登记时或 `tick` 扫描识别后打断相关等待，生成死锁报告和真人裁决请求；裁决前双方保持阻断。
+- 未登记等待：`task-status=waiting` 提示补登；宿主必须先补全依赖声明，才能进入跨任务挂起。
+- 多项依赖：单个事件到达或单项等待取消，不等于该任务的全部依赖都已解决。
+
+## 宿主接入边界
+
+- 公开 `tick` 的 `now` 仅是调用方观察时间，规范化后作为 `observedAt` 返回与审计；`scannedAt`、租约到期、排队期限和新签名租约一律使用协调器真实时钟。历史或未来观察值均不能改变授权时间；生产入口没有虚拟时钟注入。测试等待真实有界期限。
+- `tick` 与 `lock-release` 都在 `decisions` 返回本次新产生的队列超时 Confirm 请求；同时保留台账和消息，后续扫描不重复生成。
+- `tick` 是显式扫描入口；`wait-for-event` 仅在宿主实际调用并维持该进程时驱动扫描。该包不会自行安装常驻服务或全局定时器。
+- 事件唤醒的 5 秒目标依赖活跃扫描和宿主及时消费结果；只写台账、只调用一次 `dependency-wait`，均不能保证事件已投递到其他 IDE 或任务。
+- Confirm Protocol 返回结构化请求和答案协议；系统原生弹窗、跨任务消息投递与实际 callback 执行由宿主接入负责。
+- Aimlock 的读写阻断仅适用于经过其受控入口的操作；不得声称拦截所有 IDE 或操作系统文件读写。
+- 宿主退出、进程中断或结果尚未投递时，恢复后先读取台账并继续协调；不得将“未收到消息”解释为任务已完成。
+
+等待必须经事件到达、终止通知、超时处置、显式取消或死锁裁决退出。保留声明、处置和裁决证据，禁止无限期静默挂起。

package/skill/skill.json

@@ -6,5 +6,5 @@
   "name": "swarm",
   "schemaVersion": "swarm.skill.request/1.0",
   "type": "Skill",
-  "version": "v7.0.32"
+  "version": "v7.0.34"
 }

package/swarm-coordinator-model.mjs

@@ -17,6 +17,17 @@ const WAIT_EVENT_ACTIONS = new Set(['wake-with-package'])
 const TASK_STATUSES = new Set(['active', 'waiting', 'completed', 'failed', 'reclaimed'])
 const SHA256_PATTERN = /^[0-9a-f]{64}$/
 
+function findTask(state, input) {
+  const taskId = identifier(input.taskId, 'taskId')
+  const task = state.tasks.find((item) => item.taskId === taskId)
+  if (!task) coordinatorError('SWARM_COORD_TASK_NOT_FOUND', `task ${taskId} is not registered`)
+  if (task.agentId !== identifier(input.agentId, 'agentId')
+    || task.chainId !== identifier(input.chainId, 'chainId')) {
+    coordinatorError('SWARM_COORD_TASK_AUTHORITY_DENIED', 'task ownership does not match')
+  }
+  return task
+}
+
 function requireString(value, label) {
   if (typeof value !== 'string' || !value.trim()) {
     coordinatorError('SWARM_COORD_FIELD_REQUIRED', `${label} is required`)
@@ -52,6 +63,7 @@ function normalizeTaskCard(input, now = new Date().toISOString()) {
   }
   return {
     schemaVersion: 'swarm.task-card/1.0',
+    supersedesTaskId: Object.hasOwn(input, 'supersedesTaskId') ? identifier(input.supersedesTaskId, 'supersedesTaskId') : null,
     taskId: identifier(input.taskId, 'taskId'),
     agentId: identifier(input.agentId, 'agentId'),
     chainId: identifier(input.chainId, 'chainId'),
@@ -116,7 +128,7 @@ function requirementConflicts(left, right) {
 function scanTaskConflicts(candidate, tasks) {
   const conflicts = []
   for (const task of tasks) {
-    if (task.taskId === candidate.taskId || task.status === 'completed' || task.status === 'failed') continue
+    if (task.taskId === candidate.taskId || ['completed', 'failed', 'reclaimed'].includes(task.status)) continue
     const scopes = matchingScopes(candidate, task)
     if (scopes.length) conflicts.push({ type: 'file-range', risk: 'medium', taskId: task.taskId, evidence: scopes })
     const sameTarget = candidate.deployTarget !== null && candidate.deployTarget === task.deployTarget
@@ -143,6 +155,12 @@ function normalizeLockRequest(input) {
   if (!Number.isInteger(input.ttlSeconds) || input.ttlSeconds < 1 || input.ttlSeconds > 3_600) {
     coordinatorError('SWARM_COORD_LOCK_TTL_INVALID', 'ttlSeconds must be 1..3600')
   }
+  const hasQueueTimeout = Object.hasOwn(input, 'queueTimeoutMs')
+  if ((input.queueOnConflict || hasQueueTimeout)
+    && (!Number.isSafeInteger(input.queueTimeoutMs) || input.queueTimeoutMs < 1
+      || !Number.isFinite(new Date(Date.now() + input.queueTimeoutMs).getTime()))) {
+    coordinatorError('SWARM_COORD_QUEUE_TIMEOUT_REQUIRED', 'queueOnConflict requires an explicit positive queueTimeoutMs')
+  }
   const paths = lockType === 'file'
     ? requireStringArray(input.paths, 'paths', { nonEmpty: true }).map((path) => relativePath(path))
     : []
@@ -160,6 +178,7 @@ function normalizeLockRequest(input) {
     paths,
     ttlSeconds: input.ttlSeconds,
     queueOnConflict: input.queueOnConflict,
+    ...(hasQueueTimeout ? { queueTimeoutMs: input.queueTimeoutMs } : {}),
     baselineHandshakeId: input.baselineHandshakeId,
   }
 }
@@ -173,7 +192,8 @@ function locksConflict(request, lock) {
 }
 
 function normalizeWait(input, now = new Date().toISOString()) {
-  if (!Number.isInteger(input.expectedWithinMs) || input.expectedWithinMs < 1) {
+  if (!Number.isSafeInteger(input.expectedWithinMs) || input.expectedWithinMs < 1
+    || !Number.isFinite(new Date(Date.parse(now) + input.expectedWithinMs).getTime())) {
     coordinatorError('SWARM_COORD_WAIT_DURATION_INVALID', 'expectedWithinMs must be a positive integer')
   }
   if (!WAIT_EVENT_ACTIONS.has(input.onEvent) || !WAIT_TIMEOUT_ACTIONS.has(input.onTimeout)) {
@@ -258,6 +278,7 @@ function validateInputShape(input, schema) {
 }
 
 export {
+  findTask,
   coordinationMessage,
   detectWaitCycles,
   locksConflict,

package/swarm-coordinator-waits.mjs

@@ -0,0 +1,285 @@
+import { randomUUID } from 'node:crypto'
+import { coordinatorError, identifier, readCoordinationState, withCoordinationState } from './swarm-coordinator-fs.mjs'
+import { coordinationMessage, detectWaitCycles, findTask, normalizeWait, requireString, requireTaskStatus } from './swarm-coordinator-model.mjs'
+
+const LOCAL_SCHEMA = 'swarm.coordinator-local/1.0'
+const WAIT_POLL_MS = 250
+const TERMINAL_STATUSES = new Set(['completed', 'failed', 'reclaimed'])
+
+function pendingDecision(state, task) {
+  return state.decisions.some((decision) => decision.status === 'pending' && decision.agents.includes(task.agentId))
+}
+
+function hasActiveWait(state, task) {
+  return state.waits.some((wait) => wait.taskId === task.taskId && wait.status === 'active')
+}
+
+function assertTaskRunnable(state, task) {
+  if (task.status !== 'active' || hasActiveWait(state, task) || pendingDecision(state, task)) {
+    coordinatorError('SWARM_COORD_TASK_BLOCKED', 'task must resolve its dependencies and human decisions before execution')
+  }
+}
+
+function addMessage(state, type, from, to, payload, now) {
+  const message = coordinationMessage(type, from, to, payload, now)
+  state.messages.push(message)
+  return message
+}
+
+function eventRecord(publisher, event, payload, now) {
+  return { schemaVersion: 'swarm.coord-event/1.0', eventId: 'event-' + randomUUID(), publisher, event, payload, publishedAt: now }
+}
+
+function wakeWait(state, wait, resolution, event, now) {
+  wait.status = resolution
+  wait.resolvedAt = now
+  wait.resolution = event
+  const task = state.tasks.find((item) => item.taskId === wait.taskId)
+  if (task && task.status === 'waiting' && !hasActiveWait(state, task) && !pendingDecision(state, task)) {
+    task.status = 'active'
+    task.updatedAt = now
+  }
+  if (resolution === 'event-received') {
+    const entry = state.timeoutCounts.find((item) => item.waiter === wait.waiter)
+    if (entry) entry.count = 0
+  }
+  const wakePackage = { schemaVersion: 'swarm.wake-package/1.0', waitId: wait.waitId, reason: resolution,
+    event, refetchPaths: wait.refetchPaths, createdAt: now }
+  addMessage(state, 'dependency-wait', 'coordinator', wait.waiter, wakePackage, now)
+  return wakePackage
+}
+
+function routeEvent(state, event) {
+  return state.waits.filter((wait) => wait.status === 'active' && wait.waitFor === event.publisher && wait.event === event.event)
+    .map((wait) => wakeWait(state, wait, 'event-received', event, event.publishedAt))
+}
+
+function confirmationRequest(decision) {
+  const options = decision.agents.map((agentId) => ({ id: 'resume:' + agentId, label: '先恢复 ' + agentId, hint: '唤醒该智能体先解除依赖' }))
+  options.push({ id: 'abort', label: '终止等待', hint: '终止相关等待并保持任务阻塞' })
+  return { schemaVersion: 'confirm-protocol.skill.request/1.0', requestId: 'confirm-' + decision.decisionId,
+    operation: 'interaction-request', input: { interaction: {
+      schemaVersion: 'confirm.interaction/1.0', requestId: decision.decisionId, type: 'choice', question: decision.question,
+      options, default: null, timeout: null, timeoutAction: 'wait', risk: 'high', riskDescription: decision.riskDescription,
+      rememberable: false, memoryKey: '', callback: { operation: 'resolve-human', payload: { decisionId: decision.decisionId } },
+    } } }
+}
+
+function createDecision(state, kind, agents, waitIds, question, riskDescription, now) {
+  const decision = { schemaVersion: 'swarm.coord-decision/1.0', decisionId: 'decision-' + randomUUID(),
+    kind, agents: [...new Set(agents)], waitIds: [...new Set(waitIds)], question, riskDescription,
+    status: 'pending', answer: null, actorId: null, createdAt: now, resolvedAt: null }
+  state.decisions.push(decision)
+  for (const task of state.tasks.filter((item) => agents.includes(item.agentId) && !TERMINAL_STATUSES.has(item.status))) {
+    task.status = 'blocked'
+    task.blockedReason = 'human-decision'
+    task.updatedAt = now
+  }
+  const waits = state.waits.filter((wait) => waitIds.includes(wait.waitId))
+    .map(({ waitId, waiter, waitFor, event, purpose, deadlineAt }) => ({ waitId, waiter, waitFor, event, purpose, deadlineAt }))
+  addMessage(state, 'need-human', 'coordinator', 'human', { decisionId: decision.decisionId, kind, agents, waits }, now)
+  return { decision, status: 'blocked', confirmationRequired: true, confirmProtocolRequest: confirmationRequest(decision),
+    nextStep: { operation: 'confirm-protocol', instruction: 'Invoke Confirm Protocol and wait for the human answer.' } }
+}
+
+function applyCycles(state, now) {
+  const requests = []
+  for (const cycle of detectWaitCycles(state.waits)) {
+    const agents = cycle.slice(0, -1)
+    const waits = state.waits.filter((wait) => wait.status === 'active' && agents.includes(wait.waiter) && agents.includes(wait.waitFor))
+    if (!waits.length) continue
+    requests.push(createDecision(state, 'dependency-cycle', agents, waits.map((wait) => wait.waitId),
+      '检测到依赖等待成环：' + agents.join(' → ') + '。请选择先恢复的智能体。',
+      '依赖成环会导致全部相关任务无限等待，必须由真人决定执行顺序。', now))
+    const dependencies = waits.map(({ waiter, waitFor, event, purpose }) => ({ waiter, waitFor, event, purpose }))
+    for (const wait of waits) wakeWait(state, wait, 'deadlock-interrupted', { cycle, dependencies }, now)
+  }
+  return requests
+}
+
+function replayDependency(state, task, wait) {
+  const consumed = new Set(state.waits.filter((item) => item.taskId === task.taskId && item.resolution?.eventId)
+    .map((item) => item.resolution.eventId))
+  const event = state.events.findLast((item) => item.publisher === wait.waitFor && item.event === wait.event
+    && Date.parse(item.publishedAt) >= Date.parse(task.registeredAt) && !consumed.has(item.eventId))
+  if (event) return [wakeWait(state, wait, 'event-received', event, wait.startedAt)]
+  const targets = state.tasks.filter((item) => item.agentId === wait.waitFor)
+  if (targets.every((item) => TERMINAL_STATUSES.has(item.status))) {
+    return [wakeWait(state, wait, 'dependency-terminated', {
+      event: 'task-terminated', publisher: wait.waitFor, payload: { tasks: targets.map(({ taskId, status }) => ({ taskId, status })) },
+      publishedAt: wait.startedAt,
+    }, wait.startedAt)]
+  }
+  return []
+}
+
+async function dependencyWait(repositoryRoot, input) {
+  return withCoordinationState(repositoryRoot, async (state) => {
+    const task = findTask(state, { taskId: input.taskId, agentId: input.waiter, chainId: input.chainId })
+    if (TERMINAL_STATUSES.has(task.status) || pendingDecision(state, task)) {
+      coordinatorError('SWARM_COORD_TASK_BLOCKED', 'terminated tasks and pending human decisions cannot declare new dependencies')
+    }
+    const wait = normalizeWait(input)
+    if (!state.tasks.some((item) => item.agentId === wait.waitFor)) {
+      coordinatorError('SWARM_COORD_WAIT_TARGET_UNKNOWN', 'waitFor must identify a registered agent')
+    }
+    task.status = 'waiting'
+    task.updatedAt = wait.startedAt
+    state.waits.push(wait)
+    addMessage(state, 'dependency-wait', wait.waiter, wait.waitFor, {
+      waitId: wait.waitId, event: wait.event, deadlineAt: wait.deadlineAt, purpose: wait.purpose,
+    }, wait.startedAt)
+    const wakePackages = replayDependency(state, task, wait)
+    const decisions = applyCycles(state, wait.startedAt)
+    return { state, output: { schemaVersion: LOCAL_SCHEMA, wait, suspended: wait.status === 'active', decisions, wakePackages,
+      nextStep: wait.status === 'active' ? { operation: 'wait-for-event', input: { taskId: task.taskId,
+        agentId: task.agentId, chainId: task.chainId, waitId: wait.waitId } } : null },
+      audit: [{ event: 'dependency-wait', waitId: wait.waitId, waiter: wait.waiter, waitFor: wait.waitFor }] }
+  })
+}
+
+async function publishEvent(repositoryRoot, input) {
+  return withCoordinationState(repositoryRoot, async (state) => {
+    const publisher = identifier(input.publisher, 'publisher')
+    if (!state.tasks.some((task) => task.agentId === publisher)) coordinatorError('SWARM_COORD_WAIT_TARGET_UNKNOWN', 'publisher must be registered')
+    const eventName = identifier(input.event, 'event')
+    if (!input.payload || typeof input.payload !== 'object' || Array.isArray(input.payload)) {
+      coordinatorError('SWARM_COORD_EVENT_PAYLOAD_INVALID', 'payload must be an object')
+    }
+    const event = eventRecord(publisher, eventName, input.payload, new Date().toISOString())
+    state.events.push(event)
+    const wakePackages = routeEvent(state, event)
+    return { state, output: { schemaVersion: LOCAL_SCHEMA, event, wakePackages },
+      audit: [{ event: 'event-published', eventId: event.eventId, publisher, eventName }] }
+  })
+}
+
+function notifyDeadTask(state, task, now) {
+  const others = state.tasks.some((item) => item.agentId === task.agentId && !TERMINAL_STATUSES.has(item.status))
+  if (others) return []
+  return state.waits.filter((wait) => wait.status === 'active' && wait.waitFor === task.agentId)
+    .map((wait) => wakeWait(state, wait, 'dependency-terminated', {
+      event: 'task-terminated', publisher: task.agentId, payload: { taskId: task.taskId, status: task.status }, publishedAt: now,
+    }, now))
+}
+
+async function taskStatus(repositoryRoot, input) {
+  return withCoordinationState(repositoryRoot, async (state) => {
+    const task = findTask(state, input)
+    const status = requireTaskStatus(input.status)
+    if (TERMINAL_STATUSES.has(task.status) && task.status !== status) {
+      coordinatorError('SWARM_COORD_TASK_TERMINATED', 'terminal task cannot be restarted; register a new task')
+    }
+    if (status === 'active' && (pendingDecision(state, task) || hasActiveWait(state, task) || task.status === 'blocked')) {
+      coordinatorError('SWARM_COORD_TASK_BLOCKED', 'resolve dependencies or the human decision before activation')
+    }
+    const now = new Date().toISOString()
+    const undeclaredWait = status === 'waiting' && !hasActiveWait(state, task)
+    task.status = undeclaredWait ? 'blocked' : status
+    if (undeclaredWait) task.blockedReason = 'undeclared-wait'
+    task.updatedAt = now
+    const declarationMessage = undeclaredWait
+      ? addMessage(state, 'dependency-wait', 'coordinator', task.agentId, { status: 'declaration-required', taskId: task.taskId }, now) : null
+    const wakePackages = []
+    if (TERMINAL_STATUSES.has(status)) {
+      for (const wait of state.waits.filter((item) => item.taskId === task.taskId && item.status === 'active')) {
+        wakePackages.push(wakeWait(state, wait, 'waiter-terminated', { taskId: task.taskId, status }, now))
+      }
+      if (status === 'completed') {
+        const event = eventRecord(task.agentId, 'task-completed', { taskId: task.taskId, status }, now)
+        state.events.push(event)
+        wakePackages.push(...routeEvent(state, event))
+      }
+      wakePackages.push(...notifyDeadTask(state, task, now))
+    }
+    return { state, output: { schemaVersion: LOCAL_SCHEMA, task, undeclaredWait, declarationMessage, wakePackages },
+      audit: [{ event: 'task-status', taskId: task.taskId, status: task.status }] }
+  })
+}
+
+function updateTimeoutCount(state, waiter) {
+  let entry = state.timeoutCounts.find((item) => item.waiter === waiter)
+  if (!entry) { entry = { waiter, count: 0 }; state.timeoutCounts.push(entry) }
+  entry.count += 1
+  return entry.count
+}
+
+function applyTimeouts(state, now) {
+  const timedOut = state.waits.filter((wait) => wait.status === 'active' && Date.parse(wait.deadlineAt) <= Date.parse(now))
+  const decisions = [], wakePackages = []
+  for (const wait of timedOut) {
+    const count = updateTimeoutCount(state, wait.waiter)
+    if (wait.onTimeout === 'escalate-need-human' || count >= 2) {
+      decisions.push(createDecision(state, 'dependency-timeout', [wait.waiter, wait.waitFor], [wait.waitId],
+        wait.waiter + ' 等待 ' + wait.waitFor + ' 的 ' + wait.event + ' 已超时，请选择后续动作。',
+        '依赖事件未在声明期限内到达，继续静默等待可能导致任务停滞。', now))
+      wakePackages.push(wakeWait(state, wait, 'timeout-interrupted', { timeoutCount: count }, now))
+    } else {
+      const resolution = wait.onTimeout === 'abandon-wait' ? 'timeout-abandoned' : 'timeout-continued'
+      wakePackages.push(wakeWait(state, wait, resolution, { timeoutCount: count }, now))
+    }
+  }
+  return { timedOut, decisions, wakePackages }
+}
+
+async function resolveHuman(repositoryRoot, input) {
+  return withCoordinationState(repositoryRoot, async (state) => {
+    const decisionId = identifier(input.decisionId, 'decisionId')
+    const decision = state.decisions.find((item) => item.decisionId === decisionId)
+    if (!decision || decision.status !== 'pending') coordinatorError('SWARM_COORD_DECISION_NOT_PENDING', 'decision is not pending')
+    const answer = requireString(input.answer, 'answer')
+    if (![...decision.agents.map((agent) => 'resume:' + agent), 'abort'].includes(answer)) {
+      coordinatorError('SWARM_COORD_DECISION_ANSWER_INVALID', 'answer is not a declared option')
+    }
+    const now = new Date().toISOString()
+    decision.status = 'resolved'
+    decision.answer = answer
+    decision.actorId = identifier(input.actorId, 'actorId')
+    decision.resolvedAt = now
+    for (const task of state.tasks.filter((item) => answer === 'resume:' + item.agentId && !TERMINAL_STATUSES.has(item.status))) {
+      if (!pendingDecision(state, task)) {
+        task.status = hasActiveWait(state, task) ? 'waiting' : 'active'
+        task.blockedReason = null
+        task.updatedAt = now
+      }
+    }
+    return { state, output: { schemaVersion: LOCAL_SCHEMA, decision },
+      audit: [{ event: 'decision-resolved', decisionId, answer, actorId: decision.actorId }] }
+  })
+}
+
+async function cancelWait(repositoryRoot, input) {
+  return withCoordinationState(repositoryRoot, async (state) => {
+    const task = findTask(state, input)
+    const wait = state.waits.find((item) => item.waitId === identifier(input.waitId, 'waitId') && item.taskId === task.taskId)
+    if (!wait || wait.status !== 'active') coordinatorError('SWARM_COORD_WAIT_NOT_ACTIVE', 'wait is not active for this task')
+    const reason = requireString(input.reason, 'reason')
+    const wakePackage = wakeWait(state, wait, 'cancelled', { reason, actorId: task.agentId }, new Date().toISOString())
+    return { state, output: { schemaVersion: LOCAL_SCHEMA, wait, wakePackage }, audit: [{ event: 'wait-cancelled', waitId: wait.waitId, reason }] }
+  })
+}
+
+async function waitForEvent(repositoryRoot, input, tick) {
+  const waitId = identifier(input.waitId, 'waitId')
+  while (true) {
+    const before = await readCoordinationState(repositoryRoot)
+    const task = findTask(before, input)
+    const wait = before.waits.find((item) => item.waitId === waitId && item.taskId === task.taskId)
+    if (!wait) coordinatorError('SWARM_COORD_WAIT_NOT_FOUND', 'wait is not registered for this task')
+    const pending = before.decisions.filter((item) => item.status === 'pending' && item.agents.includes(task.agentId))
+    if (wait.status === 'active' && pending.length) return { schemaVersion: LOCAL_SCHEMA, status: 'blocked',
+      wait, wakePackage: null, decisions: pending, confirmProtocolRequests: pending.map(confirmationRequest) }
+    if (wait.status !== 'active') {
+      const message = before.messages.findLast((item) => item.payload.waitId === waitId && item.payload.schemaVersion === 'swarm.wake-package/1.0')
+      if (!message) coordinatorError('SWARM_COORD_WAKE_PACKAGE_MISSING', 'resolved wait has no wake package')
+      const decisions = before.decisions.filter((item) => item.status === 'pending' && item.agents.includes(task.agentId))
+      return { schemaVersion: LOCAL_SCHEMA, status: decisions.length || task.status !== 'active' ? 'blocked' : 'resolved',
+        wait, wakePackage: message.payload, decisions, confirmProtocolRequests: decisions.map(confirmationRequest) }
+    }
+    await tick(repositoryRoot, { now: new Date().toISOString() })
+    await new Promise((accept) => setTimeout(accept, Math.min(WAIT_POLL_MS, Math.max(1, Date.parse(wait.deadlineAt) - Date.now()))))
+  }
+}
+
+export { addMessage, eventRecord, routeEvent, createDecision, applyCycles, applyTimeouts, assertTaskRunnable,
+  pendingDecision, hasActiveWait, dependencyWait, publishEvent, taskStatus, resolveHuman, cancelWait, waitForEvent }