agentworkshop 0.7.44 → 0.7.47

package/server/services/workshop/runtime/task-engine/update.ts

@@ -0,0 +1,116 @@
+/**
+ * TaskEngineUpdate —— 任务更新 / 重投递 / 投递辅助
+ * (拆分层,承 TaskEngineViews;方法体与原文件逐行一致)
+ */
+import { TaskEngineViews } from './views'
+import type { A2AArtifact, Part } from '../../types/a2a'
+import type { WorkspaceTask } from '../../types/task'
+import { AppError } from '../../../../utils/errors'
+import { TERMINAL_TASK_STATES } from '../../types/task'
+import { randomUUID } from 'node:crypto'
+import { rowToTask } from './helpers'
+import { fenceToMetadata } from './lease'
+
+export abstract class TaskEngineUpdate extends TaskEngineViews {
+  /**
+   * 修改待执行任务(title/description;lead 对 worker 队列的"改")。
+   * 仅 SUBMITTED/ASSIGNED 可改(执行中/终态拒绝);
+   * 作废旧 pending 投递并重发 assign,保证 assignee 队列里的任务内容与 DB 一致。
+   */
+  updateTask(
+    taskId: string,
+    patch: { title?: string, description?: string },
+    by: string,
+  ): WorkspaceTask {
+    const task = this.requireTask(taskId)
+    if (task.state !== 'SUBMITTED' && task.state !== 'ASSIGNED') {
+      throw new AppError(400, 'INVALID_STATE', `仅待执行任务可修改(${task.state} 不可改)`)
+    }
+    if (patch.title === undefined && patch.description === undefined) {
+      return task
+    }
+    const updated = this.repos.tasks.update(taskId, {
+      title: patch.title ?? task.title,
+      description: patch.description !== undefined ? patch.description : task.description,
+    })
+    if (!updated) throw new AppError(404, 'NOT_FOUND', `任务不存在: ${taskId}`)
+    // 作废旧投递 + 重发 assign(队列中的任务内容随之为新内容)
+    this.repos.messages.consumePendingByTask(taskId)
+    this.deliverTaskMessage({
+      channelId: task.channelId,
+      taskId,
+      fromAgentId: by || null,
+      toAgentId: task.assigneeId,
+      title: updated.title,
+      description: updated.description ?? undefined,
+      kind: 'assign',
+    })
+    return rowToTask(updated)
+  }
+
+  /**
+   * 断线重连重投:非终态任务若无 pending assign 投递(消息已被消费但任务未完成,
+   * 如崩溃/异常路径),作废残留投递后向 assignee 重发 assign,由消费方终态检查保证幂等。
+   */
+  redeliverAssign(taskId: string): WorkspaceTask {
+    const task = this.requireTask(taskId)
+    if (TERMINAL_TASK_STATES[task.state]) {
+      throw new AppError(400, 'INVALID_STATE', `终态任务不可重投(${task.state})`)
+    }
+    this.repos.messages.consumePendingByTask(taskId)
+    this.deliverTaskMessage({
+      channelId: task.channelId,
+      taskId: task.id,
+      fromAgentId: task.creatorId || null,
+      toAgentId: task.assigneeId,
+      title: task.title,
+      description: task.description ?? undefined,
+      kind: 'assign',
+    })
+    return this.requireTask(taskId)
+  }
+
+  /** 任务投递消息的文本 parts:title + 可选 description */
+  protected taskParts(title: string, description?: string): Part[] {
+    const parts: Part[] = [{ text: title }]
+    if (description) parts.push({ text: description })
+    return parts
+  }
+
+  /** 向指定 agent 投递任务语义消息(assign/cancel/child-completed 统一入口) */
+  protected deliverTaskMessage(input: {
+    channelId: string
+    taskId: string
+    fromAgentId: string | null
+    toAgentId: string
+    title: string
+    description?: string
+    kind: 'assign' | 'cancel' | 'child-completed'
+    childTaskId?: string
+  }): void {
+    const metadata: Record<string, unknown> = {
+      'x-aw-task-kind': input.kind,
+      'x-aw-task-id': input.taskId,
+    }
+    if (input.childTaskId) metadata['x-aw-child-task-id'] = input.childTaskId
+    // §5.1:任务消息携带 generation/lease,worker 回合原样回传;运行时据此丢弃
+    // 重新分配之后到达的旧 worker 事件( fencing)。
+    const task = this.repos.tasks.findById(input.taskId)
+    if (task) Object.assign(metadata, fenceToMetadata(rowToTask(task)))
+    this.repos.messages.create({
+      channelId: input.channelId,
+      taskId: input.taskId,
+      fromAgentId: input.fromAgentId,
+      toAgentId: input.toAgentId,
+      role: 'ROLE_USER',
+      parts: this.taskParts(input.title, input.description),
+      metadata,
+    })
+  }
+
+  /** 初始成果:提交时附带 parts 作为首个 artifact(无 parts 则为空) */
+  protected initialArtifacts(parts?: Part[]): A2AArtifact[] {
+    if (!parts || parts.length === 0) return []
+    return [{ artifactId: randomUUID(), name: 'input', parts }]
+  }
+}

package/server/services/workshop/runtime/task-engine/views.ts

@@ -0,0 +1,169 @@
+/**
+ * TaskEngineViews —— 队列视图(全量/精简/单智能体/监督)
+ * (拆分层,承 TaskEngineContracts;方法体与原文件逐行一致)
+ */
+import { TaskEngineContracts } from './contracts'
+import type { A2AArtifact } from '../../types/a2a'
+import type { AgentTaskQueueView, RootQueueView, TaskState, WorkspaceTask } from '../../types/task'
+import type { MessageRepo } from '../../db/message.repo'
+import type { TaskRepo } from '../../db/task.repo'
+import { rowToTask, rowToTaskLite } from './helpers'
+
+export abstract class TaskEngineViews extends TaskEngineContracts {
+  /**
+   * hooks.onTaskChange:任务状态迁移的统一通知点(monitor/WS 消费)。
+   * 所有迁移必经 transition(),故状态事件不漏发;create/dispatch 的初始态直接落库,单独补发。
+   */
+  constructor(
+    protected readonly repos: { tasks: TaskRepo, messages: MessageRepo },
+    protected readonly hooks?: {
+      /**
+       * 任务变更广播(状态迁移带 state;进度变化带 progress;终态迁移经 transition
+       * 统一触发)。状态/进度的实时同步唯一出口 —— 前端/WS/monitor 据此对齐实体。
+       */
+      onTaskChange?(e: { taskId: string, channelId: string, state?: TaskState, progress?: number, agentId?: string, task?: WorkspaceTask, artifactName?: string, artifactId?: string, reassignFrom?: string, reason?: string }): void
+    },
+  ) {
+    super()
+  }
+
+  /** 单 agent 任务队列视图(queued FIFO / current / completed;派生只读投影,无第二份状态) */
+  /**
+   * FIFO 根任务队列视图(§2.2 RootQueueView)。
+   *
+   * 后端统一派生,前端不自行推导(前后端对 active root 的判断必须同源):
+   *  - `activeRoot`:最早的非终态 root(状态非 COMPLETED/FAILED/CANCELED,root_queue_seq ASC,id 稳定次级序);
+   *  - `queuedRoots`:其余非终态 root,`position` 从 2 起(1 = active);
+   *  - `completedRoots`:终态 root **计数**(§2.2 口径)。
+   */
+  rootQueueView(channelId: string): RootQueueView {
+    const queue = this.rootQueue(channelId)
+    return {
+      activeRootId: queue.activeRoot?.id ?? null,
+      activeRoot: queue.activeRoot,
+      queuedRoots: queue.queuedRoots.map((task, i) => ({ task, position: i + 2 })),
+      completedRoots: queue.completedRoots.length,
+      activeRootCount: queue.activeRoot ? 1 : 0,
+      queuedRootCount: queue.queuedRoots.length,
+    }
+  }
+
+  /** FIFO root queue: only the oldest non-terminal root is active. */
+  rootQueue(channelId: string): { activeRoot: WorkspaceTask | null, queuedRoots: WorkspaceTask[], completedRoots: WorkspaceTask[] } {
+    const roots = this.repos.tasks.listRoots(channelId).map(rowToTask)
+    const terminal = (t: WorkspaceTask) => t.state === 'COMPLETED' || t.state === 'FAILED' || t.state === 'CANCELED'
+    const open = roots.filter(t => !terminal(t))
+    return { activeRoot: open[0] ?? null, queuedRoots: open.slice(1), completedRoots: roots.filter(terminal) }
+  }
+
+  activeRootOf(channelId: string): WorkspaceTask | null {
+    return this.rootQueue(channelId).activeRoot
+  }
+
+  /** 批量队列视图:一次 list(channel) 聚合全部成员(调度快照热路径,消除 O(M) 次查询) */
+  queueViewsOf(channelId: string): Map<string, AgentTaskQueueView> {
+    const rows = this.repos.tasks.listByChannel(channelId)
+    const views = new Map<string, AgentTaskQueueView>()
+    for (const row of rows) {
+      const task = rowToTask(row)
+      let v = views.get(task.assigneeId)
+      if (!v) {
+        v = { agentId: task.assigneeId, channelId, queued: [], completed: [] }
+        views.set(task.assigneeId, v)
+      }
+      if (task.state === 'SUBMITTED' || task.state === 'ASSIGNED') v.queued.push(task)
+      else if (task.state === 'WORKING') v.current = task
+      else if (task.state === 'COMPLETED') v.completed.push(task)
+      // WAITING(等子任务)/FAILED/CANCELED 不计入队列
+    }
+    return views
+  }
+
+  /** 批量队列视图 lite 版(调度快照热路径):元数据投影,免 artifacts/history JSON 大列解析 */
+  queueViewsOfLite(channelId: string): Map<string, AgentTaskQueueView> {
+    const rows = this.repos.tasks.listByChannelMeta(channelId)
+    const views = new Map<string, AgentTaskQueueView>()
+    for (const row of rows) {
+      const task = rowToTaskLite(row)
+      let v = views.get(task.assigneeId)
+      if (!v) {
+        v = { agentId: task.assigneeId, channelId, queued: [], completed: [] }
+        views.set(task.assigneeId, v)
+      }
+      if (task.state === 'SUBMITTED' || task.state === 'ASSIGNED') v.queued.push(task)
+      else if (task.state === 'WORKING') v.current = task
+      else if (task.state === 'COMPLETED') v.completed.push(task)
+    }
+    return views
+  }
+
+  /** 任务列表 lite 版(调度快照热路径):元数据投影,免 artifacts/history JSON 大列解析。
+   *  调度决策/规则引擎/LLM 快照仅消费 id/state/parent/assignee/progress/title/description/retry;
+   *  artifacts 置空 → LLM 交付预览行降级为无交付摘要(状态/进度/标题仍完整)。 */
+  listLite(channelId: string): WorkspaceTask[] {
+    return this.repos.tasks.listByChannelMeta(channelId).map(rowToTaskLite)
+  }
+
+  /**
+   * 调度监督快照：轻量任务元数据 + Lead root 的用户输入 + 未结父任务下已完成子任务的有界交付物。
+   * artifacts 是 Lead 验收的必要事实，history 不是；每个子任务最多 4KB 文本，
+   * 最多取 24 个交付，防止长跑 Channel 把整段历史/无限产物塞入每轮 Lead prompt。
+   * 超限仍可由 Lead 通过 get_task 读取单个任务完整交付物。
+   */
+  listForSupervision(channelId: string, leadAgentId: string): WorkspaceTask[] {
+    const rows = this.repos.tasks.listByChannelMeta(channelId)
+    const artifactsByTask = new Map<string, A2AArtifact[]>()
+    for (const row of this.repos.tasks.listActiveSupervisionArtifacts(channelId, leadAgentId, 40)) {
+      let parsed: unknown
+      try {
+        parsed = JSON.parse(row.artifactsJson)
+      }
+      catch {
+        parsed = []
+      }
+      if (!Array.isArray(parsed)) continue
+      let remaining = 4_000
+      const bounded = (parsed as A2AArtifact[]).slice(0, 8).map((artifact) => {
+        const parts = (Array.isArray(artifact.parts) ? artifact.parts : []).flatMap((part) => {
+          if ('text' in part) {
+            if (remaining <= 0) return []
+            const text = part.text.slice(0, remaining)
+            remaining -= text.length
+            return [{ ...part, text }]
+          }
+          // Non-text payloads can be arbitrarily large; expose only a bounded descriptor.
+          const descriptor = JSON.stringify(part)
+          if (remaining <= 0) return []
+          const text = descriptor.slice(0, Math.min(remaining, 512))
+          remaining -= text.length
+          return [{ text: `[non-text artifact omitted] ${text}` }]
+        })
+        return { ...artifact, parts }
+      })
+      artifactsByTask.set(row.taskId, bounded)
+    }
+
+    return rows.map((row) => {
+      const task = rowToTaskLite(row)
+      return { ...task, artifacts: artifactsByTask.get(task.id) ?? [] }
+    })
+  }
+
+  queueViewOf(channelId: string, agentId: string): AgentTaskQueueView {
+    // META 投影:本视图在每次 agent 状态广播/队列上下文/调度收口时触发,
+    // 全历史整行取回(含 artifacts/history 大 JSON 解析)是最高频的重复解析 ——
+    // 队列消费方仅需 id/state/progress/title 等元数据,artifacts 置空即可
+    const rows = this.repos.tasks.listByChannelAssigneeMeta(channelId, agentId)
+    const queued: WorkspaceTask[] = []
+    let current: WorkspaceTask | undefined
+    const completed: WorkspaceTask[] = []
+    for (const row of rows) {
+      const task = rowToTaskLite(row)
+      if (task.state === 'SUBMITTED' || task.state === 'ASSIGNED') queued.push(task)
+      else if (task.state === 'WORKING') current = task
+      else if (task.state === 'COMPLETED') completed.push(task)
+      // WAITING(等子任务)/FAILED/CANCELED 不计入队列
+    }
+    return { agentId, channelId, queued, current, completed }
+  }
+}

package/server/services/workshop/runtime/user-notification-hub.ts

@@ -0,0 +1,192 @@
+/**
+ * UserNotificationHub —— v17 用户级定向通知 hub(主计划 §6)。
+ *
+ * 为什么不能复用 `broadcastPeerEvent`(scene-events.ts):
+ *  - 它对**全部**已登记 peer 广播,没有 recipient 隔离 → 通知跨用户泄漏;
+ *  - 它固定 `seq=0 / channelId=''`,没有游标、没有幂等 ID、无法可靠补发。
+ *
+ * 本模块职责:
+ *  - peer 在**认证后**绑定 userId(绑定值来自服务端 token 解析,客户端不可指定他人);
+ *  - 只向 recipientUserId 匹配的 peer 推送 `notification.created/read`;
+ *  - 通知**先持久化再发布**(调用方保证顺序;本模块只管投递);
+ *  - 幂等:同一 (recipient, eventId) 的重复发布由调用方的 user_notifications 唯一键兜底,
+ *    本模块额外做一次 peer 级去重(防同一 peer 因重连挂了两份订阅);
+ *  - 断线补发:重连时由 ws hub 用 `user_notifications` 表按游标重放(notifications 表是事实源)。
+ *
+ * 生命周期:`globalThis` 单例(HMR 跨模块实例存活,与 hitl-registry 同风格)。
+ */
+import { emitPluginEvent } from '../plugins/host.mjs'
+import { createLogger } from '../logger'
+
+const log = createLogger('workshop.notification-hub')
+
+const AEP_VERSION = 1
+
+/** 最小 peer 接口(crossws peer 的 duck typing;与 ws.ts 同风格) */
+interface WsPeer {
+  send(data: string | Uint8Array): void
+  close(code?: number, reason?: string): void
+}
+
+interface HubState {
+  /** userId → 该用户的在线 peer 集合(多标签页/多设备) */
+  byUser: Map<string, Set<WsPeer>>
+  /** peer → userId(反向索引,解绑用) */
+  peerUser: Map<WsPeer, string>
+  /** 已推送事件幂等键:peer 最近 N 条 eventId(防重连后同帧双发) */
+  seen: Map<WsPeer, string[]>
+  /** 统计(可观测性:被隔离掉多少帧) */
+  stats: {
+    published: number
+    delivered: number
+    isolated: number
+    skippedDuplicate: number
+    /** 空 recipient 调用(调用方 bug,与"用户离线"区分计数) */
+    emptyRecipient: number
+    /** 帧序列化失败(payload 含循环引用/BigInt 等) */
+    serializeErrors: number
+    /** 插件事件桥抛错次数 */
+    pluginErrors: number
+  }
+}
+
+const g = globalThis as typeof globalThis & { __userNotificationHub?: HubState }
+
+function state(): HubState {
+  return g.__userNotificationHub ??= {
+    byUser: new Map(),
+    peerUser: new Map(),
+    seen: new Map(),
+    stats: { published: 0, delivered: 0, isolated: 0, skippedDuplicate: 0, emptyRecipient: 0, serializeErrors: 0, pluginErrors: 0 },
+  }
+}
+
+/** 每个 peer 保留的最近 eventId 数(防无限增长) */
+const SEEN_CAP = 200
+
+/**
+ * 绑定 peer → userId(**认证后**调用;userId 必须来自服务端 token 解析)。
+ * 同一 peer 重复绑定不同 userId(理论不应发生)= 先解绑旧的,避免双身份。
+ */
+export function bindUserPeer(peer: WsPeer, userId: string): void {
+  const s = state()
+  const prev = s.peerUser.get(peer)
+  if (prev && prev !== userId) unbindUserPeer(peer)
+  s.peerUser.set(peer, userId)
+  let set = s.byUser.get(userId)
+  if (!set) {
+    set = new Set()
+    s.byUser.set(userId, set)
+  }
+  set.add(peer)
+}
+
+/** 解绑(连接关闭/错误时调用) */
+export function unbindUserPeer(peer: WsPeer): void {
+  const s = state()
+  const userId = s.peerUser.get(peer)
+  s.peerUser.delete(peer)
+  s.seen.delete(peer)
+  if (!userId) return
+  const set = s.byUser.get(userId)
+  if (!set) return
+  set.delete(peer)
+  if (set.size === 0) s.byUser.delete(userId)
+}
+
+/** peer 当前绑定的 userId(未认证返回 null) */
+export function userIdOfPeer(peer: WsPeer): string | null {
+  return state().peerUser.get(peer) ?? null
+}
+
+/**
+ * 向指定用户定向推送一条通知帧。
+ *
+ * **只**投递给 recipientUserId 匹配的 peer;未绑定该 userId 的 peer 永远收不到。
+ * 带 eventId 时做 peer 级幂等(同帧重复发布不重复下发)。
+ *
+ * @returns 实际投递的 peer 数
+ */
+export function publishToUser(recipientUserId: string, type: string, payload: unknown, opts: { eventId?: string } = {}): number {
+  const s = state()
+  s.stats.published += 1
+  // 插件宿主事件桥(宿主未装载时 no-op);插件异常不得中断通知扇出
+  try {
+    emitPluginEvent(type, payload)
+  }
+  catch (err) {
+    s.stats.pluginErrors += 1
+    log.warn('[user-notification-hub] 插件事件桥异常(不影响通知扇出):', err)
+  }
+  // 空 recipient 是**调用方 bug**(不是"用户离线"):分开计数,避免排障时被误读为隔离正常行为
+  if (!recipientUserId) {
+    s.stats.emptyRecipient += 1
+    log.warn(`[user-notification-hub] publishToUser 收到空 recipientUserId(type=${type}),已丢弃`)
+    return 0
+  }
+  const set = s.byUser.get(recipientUserId)
+  if (!set || set.size === 0) {
+    s.stats.isolated += 1
+    return 0
+  }
+  // 帧序列化放在 try 内:`payload` 是 unknown,循环引用 / BigInt 会让 JSON.stringify 抛错。
+  // 原实现让该异常冒泡到 hitl-registry 的 emit 循环并被吞掉 —— 结果是**该事件剩余扇出全部静默丢失**。
+  let frame: string
+  try {
+    frame = JSON.stringify({
+      v: AEP_VERSION,
+      type,
+      // 用户级事件无 channel seq 语义:显式 seq=0,但**带 eventId 幂等键**,
+      // 与 broadcastPeerEvent 的本质区别是 recipient 隔离 + 可补发(表为事实源)。
+      seq: 0,
+      at: new Date().toISOString(),
+      channelId: (payload as { channelId?: string } | null)?.channelId ?? '',
+      payload,
+    })
+  }
+  catch (err) {
+    s.stats.serializeErrors += 1
+    log.error(`[user-notification-hub] 通知帧序列化失败(type=${type}, recipient=${recipientUserId.slice(0, 8)}),已丢弃该帧:`, err)
+    return 0
+  }
+  let delivered = 0
+  for (const peer of set) {
+    if (opts.eventId) {
+      const seen = s.seen.get(peer) ?? []
+      if (seen.includes(opts.eventId)) {
+        s.stats.skippedDuplicate += 1
+        continue
+      }
+      seen.push(opts.eventId)
+      if (seen.length > SEEN_CAP) seen.splice(0, seen.length - SEEN_CAP)
+      s.seen.set(peer, seen)
+    }
+    try {
+      peer.send(frame)
+      delivered += 1
+    }
+    catch {
+      // 死连接(TCP 硬断未走 close 回调):立即解绑,防后续投递中断
+      unbindUserPeer(peer)
+    }
+  }
+  s.stats.delivered += delivered
+  return delivered
+}
+
+/** 该用户当前在线 peer 数(E2E 取证 / 排障用) */
+export function peerCountOfUser(userId: string): number {
+  return state().byUser.get(userId)?.size ?? 0
+}
+
+/** hub 统计快照(可观测性) */
+export function notificationHubStats(): HubState['stats'] & { boundUsers: number, boundPeers: number } {
+  const s = state()
+  return { ...s.stats, boundUsers: s.byUser.size, boundPeers: s.peerUser.size }
+}
+
+/** 测试用:重置 hub(仅测试脚本调用) */
+export function resetNotificationHub(): void {
+  g.__userNotificationHub = undefined
+  void state()
+}

package/server/services/workshop/settings.ts

@@ -111,6 +111,24 @@ export interface WorkshopSettings {
   idle_grace_ms: number
   /** 运行中任务的停滞判定窗口(ms):先催办一次,再过同样时长按有无产出收口 */
   stall_ms: number
+  /** supervise 观察阈值(ms):只记录 watchdog 信号,不 abort / 不取消 / 不重启 Harness */
+  supervise_watchdog_ms: number
+  /** supervise 最终安全边界(ms):超过才 abort 当前监督回合 */
+  supervise_hard_timeout_ms: number
+  max_descendants_per_root: number
+  max_active_descendants_per_root: number
+  max_canceled_descendants_per_root: number
+  max_task_depth: number
+  root_timeout_ms: number
+  max_lead_created_workers: number
+  /** §11 回滚开关:根任务 FIFO 队列 */
+  root_queue_enabled: boolean
+  /** §11 回滚开关:watchdog 只观察(关闭 = 回退为 watchdog 即中止回合) */
+  supervise_watchdog_only: boolean
+  /** §11 回滚开关:Harness 连续性(任务未空闲前不卸载进程/会话) */
+  harness_continuity_enabled: boolean
+  /** §11 回滚开关:Channel 过程记忆摘要写入 */
+  channel_memory_digest_enabled: boolean
 }
 export interface BackupSettings {
   disabled: boolean
@@ -169,6 +187,20 @@ export const ompSettings = (): OmpSettings => section<OmpSettings>('omp')
 export const harnessSettings = (): HarnessSettings => section<HarnessSettings>('harness')
 export const dcwSettings = (): DcwSettings => section<DcwSettings>('dcw')
 export const workshopSettings = (): WorkshopSettings => section<WorkshopSettings>('workshop')
+
+/**
+ * §11 回滚开关读取(缺键 = 描述符默认 = 开启)。
+ * 三个开关都只关闭「新行为」,不关闭数据库 source 唯一索引与任务终态设防 ——
+ * 那两条是正确性底线,任何配置都不得绕过。
+ */
+function workshopFlag(key: keyof WorkshopSettings, dflt: boolean): boolean {
+  const v = workshopSettings()[key]
+  return typeof v === 'boolean' ? v : dflt
+}
+export const rootQueueEnabled = (): boolean => workshopFlag('root_queue_enabled', true)
+export const superviseWatchdogOnly = (): boolean => workshopFlag('supervise_watchdog_only', true)
+export const harnessContinuityEnabled = (): boolean => workshopFlag('harness_continuity_enabled', true)
+export const channelMemoryDigestEnabled = (): boolean => workshopFlag('channel_memory_digest_enabled', true)
 export const backupSettings = (): BackupSettings => section<BackupSettings>('backup')
 export const retentionSettings = (): RetentionSettings => section<RetentionSettings>('retention')
 export const logSettings = (): LogSettings => section<LogSettings>('log')

package/server/services/workshop/types/task.ts

@@ -22,6 +22,8 @@ export interface WorkspaceTask {
   channelId: string
   /** 子任务挂主任务(主理人分解) */
   parentId?: string
+  /** Channel root FIFO sequence; only root tasks carry it */
+  rootQueueSeq?: number
   /** 当前负责 Agent */
   assigneeId: string
   /** 创建者(lead / 用户) */
@@ -38,6 +40,19 @@ export interface WorkspaceTask {
   history: A2AMessage[]
   /** 派发路由理由(koda RouteDecision 借鉴):lead 留痕"为什么派给他" */
   routeReason?: string
+  /** 群聊来源身份(仅根任务使用,用于跨标题幂等) */
+  sourceChatMessageId?: string
+  sourceChatDeliveryId?: string
+  /** 终态/关闭原因与持久化 deadline */
+  closeReason?: string
+  deadlineAt?: string
+  /** 执行交接代次(§5.1;每次新分配/重分配 +1,用于拒绝旧 worker 迟到事件) */
+  assignmentGeneration?: number
+  /** 当前执行租约 id / 持有者 / 起止时间(§2.1) */
+  executionLeaseId?: string
+  executionLeaseAgentId?: string
+  executionLeaseStartedAt?: string
+  executionLeaseRevokedAt?: string
   createdAt: string
   updatedAt: string
 }
@@ -65,6 +80,21 @@ export interface AgentTaskQueueView {
   completed: WorkspaceTask[]
 }
 
+/**
+ * 根任务队列视图(§2.2)。后端统一派生 —— 前端不得自行推导 active root,
+ * 否则前后端会对「谁在跑」给出相反结论。
+ */
+export interface RootQueueView {
+  activeRootId: string | null
+  activeRoot: WorkspaceTask | null
+  /** 排队中的 roots(不含 active);`position` 从 2 起,1 恒为 active */
+  queuedRoots: Array<{ task: WorkspaceTask, position: number }>
+  /** 已终态 root 计数 */
+  completedRoots: number
+  activeRootCount: number
+  queuedRootCount: number
+}
+
 /** harness 上下文用量快照(omp harness 有;进程内 harness 无 → 字段缺省) */
 export interface AgentContextStats {
   /** 最近已知上下文 tokens(≈ prompt 规模) */
@@ -77,6 +107,58 @@ export interface AgentContextStats {
   compacting: boolean
 }
 
+export interface SupervisionAttemptView {
+  attemptId: string | null
+  /** 归属(§2.3 channel_id / lead_agent_id;前端展示与审计) */
+  channelId?: string
+  leadAgentId?: string
+  state: 'IDLE' | 'RUNNING' | 'WATCHDOG_SIGNALED' | 'WAITING_FOR_RESULT' | 'DECISION_APPLIED' | 'ABORT_REQUESTED' | 'ABORTED'
+  startedAt: string | null
+  watchdogAt: string | null
+  /** 监督回合落定时刻(§2.3 completed_at) */
+  completedAt?: string | null
+  /** 本轮决策依据的快照修订号(= 调度 tick;§2.3 snapshot_revision) */
+  snapshotRevision?: number | null
+  activeRootId: string | null
+  watchdogCount: number
+  /** 最近一次 watchdog/监督信号时刻(§2.3 last_signal_at) */
+  lastSignalAt?: string | null
+  /** 最近一次 Lead 决策类型 wait|guide|reassign|cancel|complete|…(§2.3/§8「Lead 最后决策」) */
+  lastDecisionKind?: string | null
+}
+
+/**
+ * Harness 连续性租约只读 DTO(§2.4)。
+ * 只暴露观测字段 —— 不含凭据、不含内部 prompt;`continuityMode` 来自 registry,
+ * 一次性 CLI 如实标 `per_turn`,平台不虚假承诺同进程复用。
+ */
+export interface HarnessContinuityView {
+  leaseId: string
+  agentId: string
+  channelId: string
+  harness: string
+  continuityMode: 'persistent' | 'per_turn'
+  /** harness 子进程 pid(进程内引擎为 null) */
+  pid: number | null
+  /** harness 会话/线程身份(§2.4 session_id / thread_id;未探测到为 null) */
+  sessionId: string | null
+  /** 本租约内进程/会话被复用的回合数(§11 harness_reuse_count) */
+  reuseCount: number
+  /** 当前仍持有的非终态任务(§6.1 卸载闸门依据) */
+  activeTaskIds: string[]
+  startedAt: string
+  lastUsedAt: string
+  /** 空闲宽限到期时刻(此刻之前即便 idle 也不卸载) */
+  idleGraceUntil: string | null
+  /** 最近一次 Harness 重建原因(§6.2 last_restart_reason) */
+  lastRestartReason: string | null
+  lastRestartAt: string | null
+  /** 本租约生命周期内重建次数 */
+  restartCount: number
+  /** 按原因聚合的重启计数(§11 harness_restart_count_by_reason) */
+  harnessRestartCounts: Record<string, number>
+}
+
 /** Agent 实时状态视图(状态管理机制:idle/busy/stopped + 队列上下文) */
 export interface AgentStatusView {
   agentId: string
@@ -96,4 +178,7 @@ export interface AgentStatusView {
   completedCount: number
   /** harness 上下文用量(omp 有;进程内 harness/未知时缺省) */
   context?: AgentContextStats
+  supervision?: SupervisionAttemptView
+  /** Harness 连续性租约(§2.4/§8;只读观测面) */
+  continuity?: HarnessContinuityView
 }

package/server/utils/errors.ts

@@ -20,5 +20,7 @@ export const ErrorCodes = {
   VALIDATION_ERROR: 'VALIDATION_ERROR',
   NOT_FOUND: 'NOT_FOUND',
   CONFLICT: 'CONFLICT',
+  /** 写入保持窗:节点写成功后的防震荡锁定窗内收到新写(429) */
+  WRITE_FREQUENT: 'WRITE_FREQUENT',
   INTERNAL: 'INTERNAL_ERROR',
 } as const

package/server/utils/mojibake-guard.ts

@@ -0,0 +1,29 @@
+/**
+ * 乱码输入护栏:U+FFFD(REPLACEMENT CHARACTER)是 UTF-8 解码失败的产物,
+ * 正常用户输入几乎不会出现。含大量 FFFD 的文本一旦进入 Agent 上下文,模型会
+ * 陷入"字节考古"式思考(实测单会话空转 25 分钟+烧掉海量 token),必须在
+ * 入口处拒绝并给出可读原因,而不是静默喂给 LLM。
+ */
+import { AppError } from './errors'
+
+const FFFD = /\uFFFD/g
+
+/** 返回文本中 U+FFFD 的出现次数 */
+export function countReplacementChars(text: string): number {
+  return (text.match(FFFD) ?? []).length
+}
+
+/**
+ * 断言文本不是乱码:超过阈值即拒绝(400 INVALID_TEXT)。
+ * 阈值默认 3:容忍极个别解码噪声,拦截成片损坏。
+ */
+export function assertNotMojibake(text: string, { threshold = 3, source = 'text' }: { threshold?: number, source?: string } = {}): void {
+  const n = countReplacementChars(text)
+  if (n >= threshold) {
+    throw new AppError(
+      400,
+      'INVALID_TEXT',
+      `${source} 含 ${n} 个损坏字符(U+FFFD),疑似客户端编码错误(如 GBK/UTF-8 混用),已拒绝投递:此类内容会诱导模型空转。请以 UTF-8 编码重新发送`,
+    )
+  }
+}