cli-swarm 7.0.33 → 7.0.35

package/swarm-coordinator.mjs

@@ -1,15 +1,19 @@
-import { createHash, randomUUID } from 'node:crypto'
-import { coordinatorError, identifier, readCoordinationState,
-  withCoordinationState, writeSignedLease } from './swarm-coordinator-fs.mjs'
-import { coordinationMessage, detectWaitCycles, locksConflict, normalizeLockRequest,
-  normalizeTaskCard, normalizeWait, requireString, requireTaskStatus,
+import { createHash, randomUUID, verify } from 'node:crypto'
+import { lstat, readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import { LEASE_SCHEMA, coordinatorError, identifier, leasePayload, readCoordinationState,
+  withCoordinationReadLock, withCoordinationState, writeSignedLease } from './swarm-coordinator-fs.mjs'
+import { findTask, locksConflict, normalizeLockRequest, normalizeTaskCard, requireString,
   scanTaskConflicts, validateInputShape } from './swarm-coordinator-model.mjs'
+import { addMessage, eventRecord, routeEvent, createDecision, applyCycles, applyTimeouts,
+  assertTaskRunnable, pendingDecision, hasActiveWait, dependencyWait, publishEvent, taskStatus,
+  resolveHuman, cancelWait, waitForEvent } from './swarm-coordinator-waits.mjs'
 
 const LOCAL_SCHEMA = 'swarm.coordinator-local/1.0'
 const OPERATIONS = Object.freeze([
   'capabilities', 'register-task', 'conflict-scan', 'lock-acquire', 'lock-renew',
-  'lock-release', 'baseline-handshake', 'dependency-wait', 'event-publish',
-  'task-status', 'tick', 'resolve-human', 'status',
+  'lock-release', 'lock-queue-status', 'baseline-handshake', 'dependency-wait', 'event-publish',
+  'task-status', 'tick', 'resolve-human', 'wait-for-event', 'wait-cancel', 'status',
 ])
 
 const objectSchema = (required, properties) => ({
@@ -22,15 +26,18 @@ const TASK_CARD_SCHEMA = objectSchema(
   ['taskId', 'agentId', 'chainId', 'taskScope', 'plannedActions', 'deployTarget', 'eta', 'baselineHash', 'archConstraints'],
   { taskId: string, agentId: string, chainId: string, taskScope: stringArray,
     plannedActions: stringArray, deployTarget: nullableString, eta: string,
-    baselineHash: string, archConstraints: stringArray },
+    baselineHash: string, archConstraints: stringArray, supersedesTaskId: string },
 )
 const LOCK_SCHEMA = objectSchema(
   ['taskId', 'agentId', 'chainId', 'lockType', 'resource', 'paths', 'ttlSeconds', 'queueOnConflict', 'baselineHandshakeId'],
   { taskId: string, agentId: string, chainId: string,
     lockType: { enum: ['file', 'build', 'deploy'] }, resource: nullableString, paths: stringArray,
     ttlSeconds: { type: 'integer', minimum: 1, maximum: 3600 }, queueOnConflict: { type: 'boolean' },
-    baselineHandshakeId: nullableString },
+    baselineHandshakeId: nullableString,
+    queueTimeoutMs: { type: 'integer', minimum: 1, description: 'Explicit maximum time in the queue; required when queueOnConflict=true.' } },
 )
+LOCK_SCHEMA.allOf = [{ if: { properties: { queueOnConflict: { const: true } } },
+  then: { required: ['queueTimeoutMs'] } }]
 const WAIT_SCHEMA = objectSchema(
   ['taskId', 'chainId', 'waiter', 'waitFor', 'event', 'purpose', 'expectedWithinMs', 'onEvent', 'onTimeout', 'refetchPaths'],
   { taskId: string, chainId: string, waiter: string, waitFor: string, event: string, purpose: string,
@@ -43,6 +50,8 @@ const OPERATION_SCHEMAS = Object.freeze({
   'register-task': TASK_CARD_SCHEMA,
   'conflict-scan': objectSchema(['taskId'], { taskId: string }),
   'lock-acquire': LOCK_SCHEMA,
+  'lock-queue-status': objectSchema(['queueId', 'taskId', 'agentId', 'chainId'],
+    { queueId: string, taskId: string, agentId: string, chainId: string }),
   'lock-renew': objectSchema(['lockId', 'taskId', 'agentId', 'chainId', 'ttlSeconds'],
     { lockId: string, taskId: string, agentId: string, chainId: string,
       ttlSeconds: { type: 'integer', minimum: 1, maximum: 3600 } }),
@@ -56,90 +65,33 @@ const OPERATION_SCHEMAS = Object.freeze({
   'task-status': objectSchema(['taskId', 'agentId', 'chainId', 'status'],
     { taskId: string, agentId: string, chainId: string,
       status: { enum: ['active', 'waiting', 'completed', 'failed', 'reclaimed'] } }),
-  tick: objectSchema(['now'], { now: { type: 'string', format: 'date-time' } }),
+  tick: objectSchema(['now'], { now: { type: 'string', format: 'date-time',
+    description: 'Caller observation only; deadlines and signed leases use the coordinator clock.' } }),
   'resolve-human': objectSchema(['decisionId', 'answer', 'actorId'],
     { decisionId: string, answer: string, actorId: string }),
+  'wait-for-event': objectSchema(['taskId', 'agentId', 'chainId', 'waitId'],
+    { taskId: string, agentId: string, chainId: string, waitId: string }),
+  'wait-cancel': objectSchema(['taskId', 'agentId', 'chainId', 'waitId', 'reason'],
+    { taskId: string, agentId: string, chainId: string, waitId: string, reason: string }),
   status: objectSchema([], {}),
 })
 
 function sha256(value) { return createHash('sha256').update(value).digest('hex') }
 
-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')
+function validateReplacement(state, card) {
+  if (card.supersedesTaskId === null) return
+  const previous = state.tasks.find((task) => task.taskId === card.supersedesTaskId)
+  const pending = previous && state.decisions.some((decision) => decision.status === 'pending'
+    && decision.agents.includes(previous.agentId))
+  const covered = previous && previous.taskScope.every((path) => card.taskScope.some((scope) => (
+    path === scope || path.startsWith(scope + '/')
+  )))
+  if (!previous || previous.chainId !== card.chainId || !['failed', 'reclaimed'].includes(previous.status)
+    || pending || !covered || previous.deployTarget !== card.deployTarget
+    || previous.archConstraints.some((constraint) => !card.archConstraints.includes(constraint))
+    || state.tasks.some((task) => task.supersedesTaskId === previous.taskId)) {
+    coordinatorError('SWARM_COORD_REPLACEMENT_INVALID', 'replacement requires one failed/reclaimed task in this chain, preserved scope/constraints, and no pending decision')
   }
-  return task
-}
-
-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') {
-    task.status = 'active'
-    task.updatedAt = now
-  }
-  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)
-  addMessage(state, 'need-human', 'coordinator', 'human', { decisionId: decision.decisionId, kind, agents, waitIds }, now)
-  return { decision, status: 'blocked', confirmationRequired: true, confirmProtocolRequest: confirmationRequest(decision), nextStep: { operation: 'confirm-protocol', instruction: 'Invoke Confirm Protocol and wait for the human answer.' } }
 }
 
 async function registerTask(repositoryRoot, input) {
@@ -148,9 +100,11 @@ async function registerTask(repositoryRoot, input) {
     if (state.tasks.some((task) => task.taskId === card.taskId)) {
       coordinatorError('SWARM_COORD_TASK_EXISTS', `task ${card.taskId} is already registered`)
     }
+    validateReplacement(state, card)
     state.tasks.push(card)
     return { state, output: { schemaVersion: LOCAL_SCHEMA, task: card },
-      audit: [{ event: 'range-declare', taskId: card.taskId, agentId: card.agentId, taskScope: card.taskScope }] }
+      audit: [{ event: 'range-declare', taskId: card.taskId, agentId: card.agentId, taskScope: card.taskScope,
+        supersedesTaskId: card.supersedesTaskId }] }
   })
 }
 
@@ -205,6 +159,7 @@ async function acquireLock(repositoryRoot, input) {
   return withCoordinationState(repositoryRoot, async (state, root) => {
     const request = normalizeLockRequest(input)
     const task = findTask(state, request)
+    assertTaskRunnable(state, task)
     if (!validHandshake(task, request)) {
       coordinatorError('SWARM_COORD_BASELINE_HANDSHAKE_REQUIRED', 'build and deploy locks require the current baseline handshake')
     }
@@ -215,9 +170,11 @@ async function acquireLock(repositoryRoot, input) {
         audit: [{ event: 'lock-granted', lockId: granted.lock.lockId, taskId: request.taskId }] }
     }
     if (!request.queueOnConflict) coordinatorError('SWARM_COORD_LOCK_DENIED', 'the requested lock conflicts with an active lock')
+    const enqueuedAt = new Date().toISOString()
     const queued = { schemaVersion: 'swarm.coord-queue/1.0', queueId: `queue-${randomUUID()}`,
       request, blockingLockIds: conflicts.map((lock) => lock.lockId), status: 'queued',
-      enqueuedAt: new Date().toISOString(), resolvedAt: null }
+      enqueuedAt, deadlineAt: new Date(Date.parse(enqueuedAt) + request.queueTimeoutMs).toISOString(),
+      resolvedAt: null, grant: null, decisionId: null, confirmProtocolRequest: null }
     state.queue.push(queued)
     addMessage(state, 'lock-denied', 'coordinator', request.agentId,
       { queueId: queued.queueId, blockingLockIds: queued.blockingLockIds }, queued.enqueuedAt)
@@ -229,6 +186,7 @@ async function acquireLock(repositoryRoot, input) {
 async function renewLock(repositoryRoot, input) {
   return withCoordinationState(repositoryRoot, async (state, root) => {
     const task = findTask(state, input)
+    assertTaskRunnable(state, task)
     const lockId = identifier(input.lockId, 'lockId')
     const lock = state.locks.find((item) => item.lockId === lockId)
     if (!lock || lock.status !== 'active' || lock.taskId !== task.taskId) {
@@ -245,16 +203,122 @@ async function renewLock(repositoryRoot, input) {
   })
 }
 
+function rejectQueuedLock(state, queued, reason, now) {
+  queued.status = reason === 'queue-timeout' ? 'timed-out' : 'rejected'
+  queued.reason = reason
+  queued.resolvedAt = now
+  addMessage(state, 'lock-denied', 'coordinator', queued.request.agentId,
+    { queueId: queued.queueId, reason, request: queued.request, deadlineAt: queued.deadlineAt }, now)
+  if (reason !== 'queue-timeout') return
+  const result = createDecision(state, 'lock-queue-timeout', [queued.request.agentId], [],
+    '锁队列 ' + queued.queueId + ' 已于 ' + queued.deadlineAt + ' 超时；资源 '
+      + queued.request.resource + '，路径 ' + queued.request.paths.join(', ') + '。请核查占锁方后决定恢复或终止任务。',
+    '原队列不会再次授锁。恢复后必须提交带新明确等待上限的申请，不能把超时当作已取得锁。', now)
+  queued.decisionId = result.decision.decisionId
+  queued.confirmProtocolRequest = result.confirmProtocolRequest
+  return result
+}
+
 async function promoteQueue(state, root, now) {
-  const promoted = []
+  const promoted = [], decisions = []
   for (const queued of state.queue.filter((item) => item.status === 'queued')) {
+    if (!Number.isFinite(Date.parse(queued.deadlineAt))) {
+      rejectQueuedLock(state, queued, 'queue-deadline-missing-or-invalid', now)
+      continue
+    }
+    if (Date.parse(queued.deadlineAt) <= Date.parse(now)) {
+      decisions.push(rejectQueuedLock(state, queued, 'queue-timeout', now))
+      continue
+    }
+    const task = findTask(state, queued.request)
+    if (['completed', 'failed', 'reclaimed'].includes(task.status) || !validHandshake(task, queued.request)) {
+      rejectQueuedLock(state, queued, 'task-terminated-or-baseline-handshake-changed', now)
+      continue
+    }
+    if (task.status !== 'active' || pendingDecision(state, task) || hasActiveWait(state, task)) continue
     const conflicts = state.locks.filter((lock) => locksConflict(queued.request, lock))
     if (conflicts.length) continue
     queued.status = 'granted'
     queued.resolvedAt = now
-    promoted.push(await grantLock(state, root, queued.request, now))
+    const granted = await grantLock(state, root, queued.request, now)
+    queued.grant = { lockId: granted.lock.lockId, leasePath: granted.leasePath, lease: granted.lease }
+    promoted.push(granted)
+  }
+  return { promoted, decisions }
+}
+
+async function checkStoredQueueLease(root, grant) {
+  const lease = grant.lease
+  const expectedPath = '.coord/leases/' + identifier(lease.leaseId, 'leaseId') + '.json'
+  if (grant.leasePath !== expectedPath || lease.schemaVersion !== LEASE_SCHEMA
+    || !Number.isFinite(Date.parse(lease.issuedAt)) || Date.parse(lease.issuedAt) > Date.now()) {
+    coordinatorError('SWARM_COORD_QUEUE_GRANT_INVALID', 'queued lease path, schema or issue time is invalid')
+  }
+  const leaseFile = resolve(root, expectedPath)
+  const publicFile = resolve(root, '.coord/authority/public.pem')
+  for (const file of [leaseFile, publicFile]) {
+    const status = await lstat(file)
+    if (!status.isFile() || status.isSymbolicLink()) {
+      coordinatorError('SWARM_COORD_QUEUE_GRANT_INVALID', 'queued lease and public key must be regular files')
+    }
+  }
+  const storedLease = JSON.parse(await readFile(leaseFile, 'utf8'))
+  const publicKey = await readFile(publicFile, 'utf8')
+  if (JSON.stringify(storedLease) !== JSON.stringify(lease) || lease.authorityKeyId !== sha256(publicKey)
+    || typeof lease.signature !== 'string'
+    || !verify(null, Buffer.from(JSON.stringify(leasePayload(lease))), publicKey, Buffer.from(lease.signature, 'base64url'))) {
+    coordinatorError('SWARM_COORD_QUEUE_GRANT_INVALID', 'queued lease does not match the stored signed grant')
+  }
+}
+
+async function checkedQueueGrant(state, queued, root) {
+  const grant = queued.grant
+  const lock = grant && state.locks.find((entry) => entry.lockId === grant.lockId)
+  const request = queued.request
+  const fields = ['taskId', 'chainId', 'agentId', 'lockType', 'resource']
+  if (!lock || fields.some((field) => lock[field] !== request[field])
+    || JSON.stringify(lock.paths) !== JSON.stringify(request.paths)
+    || lock.leasePath !== grant.leasePath || !grant.lease
+    || ['lockId', 'leaseId', 'chainId', 'agentId', 'lockType', 'resource', 'issuedAt', 'expiresAt']
+      .some((field) => lock[field] !== grant.lease[field])
+    || JSON.stringify(lock.paths) !== JSON.stringify(grant.lease.paths)) {
+    coordinatorError('SWARM_COORD_QUEUE_GRANT_INVALID', 'queued grant does not match its original request and current lease')
   }
-  return promoted
+  if (lock.status !== 'active' || !Number.isFinite(Date.parse(lock.expiresAt)) || Date.parse(lock.expiresAt) <= Date.now()) {
+    coordinatorError('SWARM_COORD_QUEUE_GRANT_EXPIRED', 'queued grant is no longer an active unexpired lock')
+  }
+  await checkStoredQueueLease(root, grant)
+  return { lock, leasePath: grant.leasePath, lease: grant.lease }
+}
+
+async function lockQueueStatus(repositoryRoot, input) {
+  return withCoordinationReadLock(repositoryRoot, async (state, root) => {
+    const task = findTask(state, input)
+    const queueId = identifier(input.queueId, 'queueId')
+    const queued = state.queue.find((entry) => entry.queueId === queueId)
+    if (!queued || ['taskId', 'agentId', 'chainId'].some((field) => queued.request[field] !== input[field])) {
+      coordinatorError('SWARM_COORD_QUEUE_NOT_FOUND', 'queue does not belong to the requested task, agent and chain')
+    }
+    if (['completed', 'failed', 'reclaimed'].includes(task.status) || ['rejected', 'timed-out'].includes(queued.status)) {
+      return { schemaVersion: LOCAL_SCHEMA, status: 'blocked', queued, reason: 'queue-no-longer-runnable',
+        confirmationRequired: queued.status === 'timed-out',
+        decisionId: queued.decisionId, confirmProtocolRequest: queued.confirmProtocolRequest,
+        requiredAction: 'Resolve any human decision and submit a new explicit request; this queue cannot grant a lock.' }
+    }
+    if (queued.status === 'queued') {
+      if (!Number.isFinite(Date.parse(queued.deadlineAt)) || Date.parse(queued.deadlineAt) <= Date.now()) {
+        return { schemaVersion: LOCAL_SCHEMA, status: 'blocked', queued, reason: 'queue-deadline-expired-or-missing',
+          requiredAction: 'Run tick to record the terminal queue outcome; do not repeat lock-acquire.' }
+      }
+      return { schemaVersion: LOCAL_SCHEMA, status: 'queued', queued }
+    }
+    if (queued.status !== 'granted') coordinatorError('SWARM_COORD_QUEUE_STATE_INVALID', 'unknown queued lock state')
+    assertTaskRunnable(state, task)
+    if (!validHandshake(task, queued.request)) {
+      coordinatorError('SWARM_COORD_BASELINE_HANDSHAKE_REQUIRED', 'queued grant requires the original current baseline handshake')
+    }
+    return { schemaVersion: LOCAL_SCHEMA, status: 'granted', queueId, ...await checkedQueueGrant(state, queued, root) }
+  })
 }
 
 async function releaseLock(repositoryRoot, input) {
@@ -271,9 +335,9 @@ async function releaseLock(repositoryRoot, input) {
     const event = eventRecord(lock.agentId, 'lock-released', { lockId, resource: lock.resource }, now)
     state.events.push(event)
     const wakePackages = routeEvent(state, event)
-    const promoted = await promoteQueue(state, root, now)
-    return { state, output: { schemaVersion: LOCAL_SCHEMA, released: lock, promoted, wakePackages },
-      audit: [{ event: 'lock-released', lockId, taskId: task.taskId }] }
+    const { promoted, decisions } = await promoteQueue(state, root, now)
+    return { state, output: { schemaVersion: LOCAL_SCHEMA, released: lock, promoted, wakePackages, decisions },
+      audit: [{ event: 'lock-released', lockId, taskId: task.taskId, queueTimeouts: decisions.length }] }
   })
 }
 
@@ -288,7 +352,12 @@ async function baselineHandshake(repositoryRoot, input) {
     task.baselineHandshake = matched ? {
       handshakeId: `handshake-${randomUUID()}`, baselineHash: observed, checkedAt: now,
     } : null
-    if (!matched) task.status = 'waiting'
+    if (!matched) { task.status = 'blocked'; task.blockedReason = 'baseline-mismatch' }
+    else if (!hasActiveWait(state, task) && !pendingDecision(state, task)
+      && task.status === 'blocked' && task.blockedReason === 'baseline-mismatch') {
+      task.status = 'active'
+      task.blockedReason = null
+    }
     const message = addMessage(state, 'baseline-handshake', 'coordinator', task.agentId, {
       matched, expectedBaselineHash: task.baselineHash, observedBaselineHash: observed,
       refetchPaths: input.refetchPaths,
@@ -300,162 +369,36 @@ async function baselineHandshake(repositoryRoot, input) {
   })
 }
 
-function applyCycles(state, now) {
-  const cycles = detectWaitCycles(state.waits)
-  const requests = []
-  for (const cycle of cycles) {
-    const agents = cycle.slice(0, -1)
-    const waits = state.waits.filter((wait) => wait.status === 'active'
-      && agents.includes(wait.waiter) && agents.includes(wait.waitFor))
-    for (const wait of waits) wakeWait(state, wait, 'deadlock-interrupted', { cycle }, now)
-    requests.push(createDecision(state, 'dependency-cycle', agents, waits.map((wait) => wait.waitId),
-      `检测到依赖等待成环：${agents.join(' → ')}。请选择先恢复的智能体。`,
-      '依赖成环会导致全部相关任务无限等待，必须由真人决定执行顺序。', now))
-  }
-  return requests
-}
-
-async function dependencyWait(repositoryRoot, input) {
-  return withCoordinationState(repositoryRoot, async (state) => {
-    const task = findTask(state, { taskId: input.taskId, agentId: input.waiter, chainId: input.chainId })
-    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 decisions = applyCycles(state, wait.startedAt)
-    return { state, output: { schemaVersion: LOCAL_SCHEMA, wait, suspended: wait.status === 'active', decisions },
-      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')
-    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) {
-  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)
-    const now = new Date().toISOString()
-    task.status = status
-    task.updatedAt = now
-    const undeclaredWait = status === 'waiting' && !state.waits.some((wait) => (
-      wait.status === 'active' && wait.taskId === task.taskId
-    ))
-    let declarationMessage = null
-    if (undeclaredWait) declarationMessage = addMessage(state, 'dependency-wait', 'coordinator', task.agentId,
-      { status: 'declaration-required', taskId: task.taskId }, now)
-    const wakePackages = status === 'failed' || status === 'reclaimed'
-      ? notifyDeadTask(state, task, now) : []
-    return { state, output: { schemaVersion: LOCAL_SCHEMA, task, undeclaredWait,
-      declarationMessage, wakePackages }, audit: [{ event: 'task-status', taskId: task.taskId, 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 = []
-  const wakePackages = []
-  for (const wait of timedOut) {
-    const count = updateTimeoutCount(state, wait.waiter)
-    if (wait.onTimeout === 'escalate-need-human' || count >= 2) {
-      wakePackages.push(wakeWait(state, wait, 'timeout-interrupted', { timeoutCount: count }, now))
-      decisions.push(createDecision(state, 'dependency-timeout', [wait.waiter, wait.waitFor], [wait.waitId],
-        `${wait.waiter} 等待 ${wait.waitFor} 的 ${wait.event} 已超时，请选择后续动作。`,
-        '依赖事件未在声明期限内到达，继续静默等待可能导致任务停滞。', 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 tick(repositoryRoot, input) {
   return withCoordinationState(repositoryRoot, async (state, root) => {
-    const nowMs = Date.parse(input.now)
-    if (!Number.isFinite(nowMs)) coordinatorError('SWARM_COORD_NOW_INVALID', 'now must be an ISO date-time')
+    const observedMs = Date.parse(input.now)
+    if (typeof input.now !== 'string' || !Number.isFinite(observedMs)) {
+      coordinatorError('SWARM_COORD_NOW_INVALID', 'now must be an ISO date-time observation')
+    }
+    const observedAt = new Date(observedMs).toISOString()
+    const nowMs = Date.now()
     const now = new Date(nowMs).toISOString()
     const expiredLocks = state.locks.filter((lock) => lock.status === 'active'
       && Date.parse(lock.expiresAt) <= nowMs)
+    const lockWakePackages = []
     for (const lock of expiredLocks) {
       lock.status = 'expired'
       lock.releasedAt = now
+      const event = eventRecord(lock.agentId, 'lock-released', { lockId: lock.lockId, resource: lock.resource, reason: 'expired' }, now)
+      state.events.push(event)
+      lockWakePackages.push(...routeEvent(state, event))
     }
-    const promoted = await promoteQueue(state, root, now)
+    const { promoted, decisions } = await promoteQueue(state, root, now)
     const timeouts = applyTimeouts(state, now)
     const cycles = applyCycles(state, now)
-    return { state, output: { schemaVersion: LOCAL_SCHEMA, expiredLocks, promoted,
-      timedOutWaits: timeouts.timedOut, wakePackages: timeouts.wakePackages,
-      decisions: [...timeouts.decisions, ...cycles] },
-    audit: [{ event: 'coordination-tick', expiredLocks: expiredLocks.length,
+    return { state, output: { schemaVersion: LOCAL_SCHEMA, observedAt, scannedAt: now, expiredLocks, promoted,
+      timedOutWaits: timeouts.timedOut, wakePackages: [...lockWakePackages, ...timeouts.wakePackages],
+      decisions: [...decisions, ...timeouts.decisions, ...cycles] },
+    audit: [{ event: 'coordination-tick', observedAt, scannedAt: now, queueTimeouts: decisions.length, expiredLocks: expiredLocks.length,
       timedOutWaits: timeouts.timedOut.length, deadlocks: cycles.length }] }
   })
 }
 
-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')
-    const allowed = new Set([...decision.agents.map((agent) => `resume:${agent}`), 'abort'])
-    if (!allowed.has(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
-    if (answer.startsWith('resume:')) {
-      const agent = answer.slice('resume:'.length)
-      for (const task of state.tasks.filter((item) => item.agentId === agent && item.status === 'waiting')) {
-        task.status = 'active'
-        task.updatedAt = now
-      }
-    }
-    return { state, output: { schemaVersion: LOCAL_SCHEMA, decision },
-      audit: [{ event: 'decision-resolved', decisionId, answer, actorId: decision.actorId }] }
-  })
-}
-
 async function coordinatorStatus(repositoryRoot) {
   const state = await readCoordinationState(repositoryRoot)
   return { schemaVersion: LOCAL_SCHEMA, state }
@@ -465,6 +408,7 @@ const HANDLERS = Object.freeze({
   'register-task': registerTask,
   'conflict-scan': conflictScan,
   'lock-acquire': acquireLock,
+  'lock-queue-status': lockQueueStatus,
   'lock-renew': renewLock,
   'lock-release': releaseLock,
   'baseline-handshake': baselineHandshake,
@@ -473,6 +417,8 @@ const HANDLERS = Object.freeze({
   'task-status': taskStatus,
   tick,
   'resolve-human': resolveHuman,
+  'wait-for-event': (root, input) => waitForEvent(root, input, tick),
+  'wait-cancel': cancelWait,
   status: coordinatorStatus,
 })