cs-bots 0.1.1 → 0.7.4

package/src/fence.js

@@ -0,0 +1,142 @@
+/**
+ * cs-bots /api 鉴权围栏 —— **公网暴露的 API 必须有门**。
+ *
+ * 为什么需要这个文件（2026-11-04 实测）：
+ *   修复前 cs-bots 的 HTTP 面**完全没有鉴权**——
+ *   `curl -X POST http://<公网IP>/cs-bots/api/tasks -d '{"subject":"x"}'` 返回 200，
+ *   任何知道地址的人都能建任务、改记忆、写房间、改 Bot 注册表。
+ *   对比：cs-guard 有完整围栏、cs-myfree 有校验，唯独 cs-bots 裸奔。
+ *   这不仅是"数据被改"，更会把「受保护区写闸门」这类下游防护**从更高层绕过去**
+ *   （比如直接往 roster/memory 事件流里塞条目），所以必须在 API 层堵死。
+ *
+ * 判定顺序（与 cs-guard/web/guard.js 同款思路，但**本文件独立实现**——
+ * cs-bots 的铁律是"运行时不依赖其他插件"，不能 import cs-guard）：
+ *   ① Origin 与 Host 不同源 → 403（防 CSRF）
+ *   ② 宿主 connection 服务可用 → 交给它做**真实**会话校验（签名/cookie 有效性）
+ *   ③ 宿主校验能力缺失 → 拒绝一切**经代理**的请求（fail-closed），
+ *      非代理请求放行（本机直连 / 测试替身；服务只监听 127.0.0.1，外部进不来）
+ *
+ * 为什么第 ③ 条不是一律拒绝：本仓的 `test/api.test.mjs` 用假 req/res 直接调 handler，
+ * 没有 socket 也没有 connection 服务。一律拒绝会让整个测试套件失效，
+ * 逼着人关掉围栏——那才是真正的安全隐患。区分"经代理"与"非经代理"是准确的边界。
+ */
+
+/** 判定 loopback 地址。 */
+function isLoopbackAddr(addr) {
+  if (typeof addr !== 'string' || addr === '') return false
+  return addr === '::1' || addr === '127.0.0.1' || addr.startsWith('127.') || addr === '::ffff:127.0.0.1'
+}
+
+/** 请求是否经过反向代理（nginx 等会加这些头）。 */
+export function isProxiedRequest(request) {
+  const headers = request?.headers || {}
+  return Boolean(
+    headers['x-forwarded-for'] || headers['x-forwarded-proto']
+    || headers['x-forwarded-host'] || headers['x-real-ip'],
+  )
+}
+
+/** 安全取宿主的 connection 服务（拿不到就返回 null，不抛）。 */
+export function safeGetConnection(getConnection) {
+  try {
+    const conn = typeof getConnection === 'function' ? getConnection() : getConnection
+    return conn && typeof conn.requestRejection === 'function' ? conn : null
+  } catch {
+    return null
+  }
+}
+
+/** 委托宿主做真实会话校验。 */
+export function verifySession(request, conn) {
+  try {
+    const rejection = conn.requestRejection(request)
+    // 宿主契约：undefined/null/0 表示放行；401 未认证；其余为 403 禁止
+    if (rejection === undefined || rejection === null || rejection === 0) return { ok: true }
+    const status = rejection === 401 ? 401 : 403
+    return {
+      ok: false,
+      status,
+      reason: status === 401 ? 'invalid-or-missing-session' : 'untrusted-authority-or-forbidden',
+    }
+  } catch {
+    return { ok: false, status: 403, reason: 'auth-check-failed' }
+  }
+}
+
+/**
+ * 判定一个 API 请求是否放行。
+ *
+ * @param {any} request  Node IncomingMessage（或测试替身）
+ * @param {{ getConnection?: (() => any) | any }} [opts]
+ * @returns {{ ok: boolean, status?: number, reason?: string }}
+ */
+export function judge(request, { getConnection } = {}) {
+  const headers = request?.headers || {}
+
+  // ① 同源校验（防 CSRF）：带了 Origin 就必须与 Host 一致
+  const origin = headers.origin
+  const hostHeader = headers.host
+  if (typeof origin === 'string' && origin !== '') {
+    let originHost = null
+    try { originHost = new URL(origin).host } catch { originHost = null }
+    if (originHost === null || originHost !== hostHeader) {
+      return { ok: false, status: 403, reason: 'cross-origin' }
+    }
+  }
+
+  // ② 宿主校验能力可用 → 真实校验，**不论是否经代理**
+  const conn = safeGetConnection(getConnection)
+  if (conn) return verifySession(request, conn)
+
+  // ③ 宿主校验能力缺失：经代理的请求一律拒绝（公网路径 fail-closed）
+  if (isProxiedRequest(request)) {
+    return { ok: false, status: 403, reason: 'auth-unavailable-for-proxied' }
+  }
+
+  // 非代理：本机直连（服务只绑 127.0.0.1）或测试替身 → 放行
+  return { ok: true }
+}
+
+/**
+ * 造一个带缓存的判定器（避免每个请求都去 reflect 一次 ctx）。
+ *
+ * @param {{ ctx: any, warn?: Function }} input
+ * @returns {{ judgeHttp: (request: any) => {ok:boolean,status?:number,reason?:string},
+ *            mode: () => 'host-session'|'proxy-denied' }}
+ */
+export function createFence({ ctx, warn } = {}) {
+  let warnedNoConnection = false
+
+  const getConnection = () => {
+    try {
+      if (typeof ctx?.get === 'function') {
+        const viaGet = ctx.get('connection', false)
+        if (viaGet) return viaGet
+      }
+      return ctx?.connection ?? null
+    } catch {
+      return null
+    }
+  }
+
+  // 启动时探一次：把"围栏处在哪种模式"明确写进日志，
+  // 免得以后有人以为有门、其实门是虚掩的（这次 P0 就是这么漏的）。
+  const probe = safeGetConnection(getConnection)
+  if (!probe) {
+    warnedNoConnection = true
+    warn?.(
+      '[cs-bots/fence] 未拿到宿主 connection 服务 → API 围栏降级为「拒绝一切经代理请求」模式。'
+      + '本机直连（127.0.0.1）与测试替身仍可访问；公网路径一律 403。'
+      + '若你是在公网使用本插件，这说明会话校验失效，请检查 DSH 版本/装配。',
+    )
+  }
+
+  return {
+    judgeHttp(request) {
+      return judge(request, { getConnection })
+    },
+    mode() {
+      return safeGetConnection(getConnection) ? 'host-session' : 'proxy-denied'
+    },
+  }
+}

package/src/index.js

@@ -17,9 +17,22 @@ import { createRoom } from './room.js'
 import { createMemory } from './memory.js'
 import { installTools } from './tools.js'
 import { setServices } from './registry.js'
-import { service, stateDir as kernelStateDir } from './kernel.js'
+import { service, stateDir as kernelStateDir, onLlmStream, sessionMeta, readSessionWatermark as kernelWatermark } from './kernel.js'
+import { installLlmStreamHint } from './routing/hints.js'
 import { installApi } from './api.js'
+import { createDeliveryWatch, DEFAULT_GRACE_MS, DEFAULT_TICK_MS } from './delivery-watch.js'
 import { createLibrary } from './library.js'
+import { createDiscipline } from './discipline.js'
+import { createTodo } from './todo.js'
+import { createScratch } from './scratch.js'
+import { createPrompts } from './prompts.js'
+import { createSuggest } from './suggest.js'
+import { createReviewer } from './reviewer.js'
+import { createMetrics } from './metrics.js'
+import { createVerify } from './verify.js'
+import { createCycle } from './cycle.js'
+import { createTeams } from './teams.js'
+import { createSubscription } from './subscription.js'
 import { createDirBrowser } from './dirbrowse.js'
 import { loadSettings } from './settings.js'
 import { probeHost, formatReport } from './compat.js'
@@ -111,8 +124,20 @@ function applyInner(ctx, config, { log, warn }) {
   }
 
   try {
-    services.board = createBoard(ctx, { stateDir: config.stateDir, leaseMs: settings.defaultLeaseMs })
+    // ⚠️ 2026-11-05（P0）：createBoard 必须拿到 settings —— wipLimitPerBot（WIP 上限）
+    //   与 requireTriageForReady（Ready 闸门）都从 config.settings 读。只传 stateDir 会让
+    //   平台设置对任务板静默失效（永远退回代码内默认值），且用户改了设置看不到任何变化。
+    services.board = createBoard(ctx, { stateDir: config.stateDir, leaseMs: settings.defaultLeaseMs, settings })
     log(`[cs-bots] BoardService 就绪（stateDir=${services.board.paths?.stateDir ?? '?'}）`)
+    // ⚠️ 修复（2026-11-04 测试，P1-4）：expireLeases 之前无任何调用者，
+    //   owner 崩溃/失联后任务永久停在 in_progress（连"重启时回收"都不做）。
+    //   现在启动时先回收一次过期租约（失败不阻塞装配）。
+    try {
+      const recycled = services.board.expireLeases()
+      if (recycled.length > 0) log(`[cs-bots] 启动回收过期租约：${recycled.join(', ')}`)
+    } catch (error) {
+      warn(`[cs-bots] 启动回收过期租约失败（不影响装配）：${error?.message ?? error}`)
+    }
   } catch (error) {
     warn(`[cs-bots] BoardService 装配失败 → 降级（无任务板）：${error?.message ?? error}`)
     services.board = undefined
@@ -138,7 +163,16 @@ function applyInner(ctx, config, { log, warn }) {
   }
 
   try {
-    services.memory = createMemory(ctx, { stateDir: config.stateDir, entryMax: settings.memoryEntryMax, splitOnOverflow: settings.memorySplitOnOverflow })
+    services.memory = createMemory(ctx, {
+      stateDir: config.stateDir,
+      entryMax: settings.memoryEntryMax,
+      splitOnOverflow: settings.memorySplitOnOverflow,
+      progressiveDisclosure: settings.keyProgressiveDisclosure,
+      fullInjectThreshold: settings.keyFullInjectThreshold,
+      fullInjectCharLimit: settings.keyFullInjectCharLimit,
+      entryDatePrefix: settings.entryDatePrefix,
+      perTurnWrites: settings.perTurnWrites,
+    })
     log(`[cs-bots] MemoryService 就绪（stateDir=${services.memory.paths?.stateDir ?? '?'}）`)
   } catch (error) {
     warn(`[cs-bots] MemoryService 装配失败 → 降级（无分层记忆）：${error?.message ?? error}`)
@@ -170,12 +204,160 @@ function applyInner(ctx, config, { log, warn }) {
 
   // ── 技能库 / 工作流库（全局可复用资产，Bot 与任务可关联）──────────────
   try {
-    services.library = createLibrary(ctx, { stateDir: config.stateDir ?? kernelStateDir() })
+    services.library = createLibrary(ctx, {
+      stateDir: config.stateDir ?? kernelStateDir(),
+      skillMaxBytes: settings.skillMaxBytes,
+      skillReviewEnabled: settings.skillReviewEnabled,
+    })
     log('[cs-bots] library 就绪')
   } catch (error) {
     warn(`[cs-bots] library 装配失败（技能库/工作流库不可用）：${error?.message ?? error}`)
   }
 
+  // ── 分级纪律体系（全局/工作区/房间/Bot 四级，注入到各层级上下文）──────────
+  try {
+    services.discipline = createDiscipline(ctx, { stateDir: config.stateDir ?? kernelStateDir() })
+    log(`[cs-bots] discipline 就绪（${services.discipline.stats().total} 条纪律）`)
+  } catch (error) {
+    warn(`[cs-bots] discipline 装配失败（分级纪律不可用）：${error?.message ?? error}`)
+  }
+
+  // ── 四轨待办（生活/工作/项目/每日 + 四象限 + 逾期）─────────────────────────
+  try {
+    services.todo = createTodo(ctx, { stateDir: config.stateDir ?? kernelStateDir() })
+    log(`[cs-bots] todo 就绪（${services.todo.stats?.().total ?? 0} 条待办）`)
+  } catch (error) {
+    warn(`[cs-bots] todo 装配失败（待办不可用）：${error?.message ?? error}`)
+  }
+
+  // ── 便签（单文件随手记，原子写）────────────────────────────────────────────
+  try {
+    services.scratch = createScratch(ctx, { stateDir: config.stateDir ?? kernelStateDir() })
+    log('[cs-bots] scratch 就绪')
+  } catch (error) {
+    warn(`[cs-bots] scratch 装配失败（便签不可用）：${error?.message ?? error}`)
+  }
+
+  // ── 提示词库 + 注入轨 ──────────────────────────────────────────────────────
+  try {
+    services.prompts = createPrompts(ctx, { stateDir: config.stateDir ?? kernelStateDir() })
+    log(`[cs-bots] prompts 就绪（${services.prompts.stats?.().total ?? 0} 条提示词）`)
+  } catch (error) {
+    warn(`[cs-bots] prompts 装配失败（提示词库不可用）：${error?.message ?? error}`)
+  }
+
+  // ── 建议确认队列（模型只能提议，人点采纳才落库）───────────────────────────
+  try {
+    services.suggest = createSuggest(ctx, { stateDir: config.stateDir ?? kernelStateDir() })
+    log('[cs-bots] suggest 就绪')
+  } catch (error) {
+    warn(`[cs-bots] suggest 装配失败（建议队列不可用）：${error?.message ?? error}`)
+  }
+
+  // ── 自审调度（每 N 回合提醒模型做一次记忆自检）─────────────────────────────
+  try {
+    services.reviewer = createReviewer(ctx, {
+      stateDir: config.stateDir ?? kernelStateDir(),
+      memory: services.memory,
+      suggest: services.suggest,
+      interval: settings.reviewInterval,
+      enabled: settings.reviewEnabled,
+      mode: settings.reviewMode,
+      writeGuard: settings.perTurnWriteGuard,
+      writeGuardThreshold: settings.writeGuardThreshold,
+    })
+    log(`[cs-bots] reviewer 就绪（每 ${services.reviewer.status?.().interval ?? '?'} 回合）`)
+  } catch (error) {
+    warn(`[cs-bots] reviewer 装配失败（自审调度不可用）：${error?.message ?? error}`)
+  }
+
+  // ── 测量（PDCA 的 Check 数据面）────────────────────────────────────────────
+  try {
+    services.metrics = createMetrics(ctx, { stateDir: config.stateDir ?? kernelStateDir() })
+    log('[cs-bots] metrics 就绪（PDCA 测量面）')
+  } catch (error) {
+    warn(`[cs-bots] metrics 装配失败（测量不可用）：${error?.message ?? error}`)
+  }
+
+  // ── 验收证据（PDCA 的 Check 证据自动化）─────────────────────────────────────
+  try {
+    services.verify = createVerify(ctx, { stateDir: config.stateDir ?? kernelStateDir() })
+    log('[cs-bots] verify 就绪（验收证据自动化）')
+  } catch (error) {
+    warn(`[cs-bots] verify 装配失败（验收证据不可用）：${error?.message ?? error}`)
+  }
+
+  // ── 复盘与标准化（PDCA 的 Act）──────────────────────────────────────────────
+  // suggest 缺失也能装配（review() 会降级为「只记复盘内容」）。
+  try {
+    services.cycle = createCycle(ctx, {
+      stateDir: config.stateDir ?? kernelStateDir(),
+      suggest: services.suggest,
+    })
+    log('[cs-bots] cycle 就绪（复盘与标准化）')
+  } catch (error) {
+    warn(`[cs-bots] cycle 装配失败（复盘不可用）：${error?.message ?? error}`)
+  }
+
+  // ── 大/小团队（Lead 聚合管理）───────────────────────────────────────────────
+  try {
+    services.teams = createTeams(ctx, { stateDir: config.stateDir ?? kernelStateDir() })
+    log(`[cs-bots] teams 就绪（${services.teams.stats().total} 个团队）`)
+  } catch (error) {
+    warn(`[cs-bots] teams 装配失败（团队不可用）：${error?.message ?? error}`)
+  }
+
+  // ── 任务订阅（改造07 · 借鉴 Super-agent Subscription 扇出）──────────────────
+  // 让房间讨论的后续消息自动到达相关任务，不需要再 @ Bot。
+  try {
+    services.subscription = createSubscription(ctx, { stateDir: config.stateDir ?? kernelStateDir() })
+    log(`[cs-bots] subscription 就绪（${services.subscription.stats().active} 条活订阅）`)
+  } catch (error) {
+    warn(`[cs-bots] subscription 装配失败（房间→任务扇出不可用）：${error?.message ?? error}`)
+  }
+
+  // ── 投递回执看护（2026-11-09 · 补 superagent 的 inputsRead 那一层）─────────────
+  // 「投递成功」不等于「真的在跑」：现场出现过 wake 记 sent、会话 turns/steps 全 0、
+  // 任务卡在「进行中」且页面无异常。看护在投递后盯事件水位，超时没涨就把
+  // 「已投递但执行者未开始动作」写进 task.delivery.error，让它以 person/delivery 显形。
+  try {
+    const graceMs = Number(process?.env?.CS_BOTS_DELIVERY_GRACE_MS) || DEFAULT_GRACE_MS
+    services.deliveryWatch = createDeliveryWatch(ctx, {
+      logger: { info: log, warn },
+      watermark: (sessionId) => kernelWatermark(ctx, sessionId),
+      markFailure: async (taskId, reason) => {
+        const board = services.board
+        if (!board) return false
+        const current = board.get(taskId)
+        if (!current || current.status === 'deleted' || current.status === 'completed') return false
+        try {
+          // ⚠️ **合并写入**（2026-11-09）：`board.set` 对 `delivery` 是整体替换，
+          // 直接写 `{ error, at, by }` 会抹掉这个字段上已有的其它键
+          // （比如 api.js 记下的 `clearedAt`/`clearedBy`）。先读再展开。
+          const prev = (current.delivery && typeof current.delivery === 'object') ? current.delivery : {}
+          await board.update({
+            id: taskId,
+            expectedRev: current.rev,
+            action: 'set',
+            byId: 'cs-bots.watchdog',
+            delivery: { ...prev, error: reason, at: Date.now(), by: 'cs-bots.watchdog' },
+          })
+          return true
+        } catch {
+          return false
+        }
+      },
+      options: {
+        graceMs,
+        tickMs: Number(process?.env?.CS_BOTS_DELIVERY_TICK_MS) || DEFAULT_TICK_MS,
+      },
+    })
+    log(`[cs-bots] 投递回执看护就绪（宽限 ${Math.round(graceMs / 1000)}s）`)
+  } catch (error) {
+    warn(`[cs-bots] 投递回执看护装配失败（投递仍可用，只是不追踪回执）：${error?.message ?? error}`)
+    services.deliveryWatch = undefined
+  }
+
   // ── 页面数据面：HTTP API（页面层靠它拿数据；没有它 UI 是空壳）──────────────
   services.apiDispose = installApi(ctx, { warn })
 
@@ -186,6 +368,45 @@ function applyInner(ctx, config, { log, warn }) {
     log(`[cs-bots] 已注册 ${toolNames.length} 个工具：${toolNames.join(', ')}`)
   }
 
+  // ── 复杂度路由：llm/stream 拦截 → cs-myfree 旁路 hint 注册表 ────────────────
+  // 契约 §6。三条纪律都落在这里：
+  //   ① 钩子**总是尝试注册**（cs-myfree 后装载也能立刻生效）；
+  //   ② 没装 cs-myfree 只是 `installed:false`，不进日志噪音、更不影响对话；
+  //   ③ 任何异常都只 warn —— 路由优化不值得拿可用性换。
+  try {
+    const routing = installLlmStreamHint(ctx, { onLlmStream }, {
+      warn,
+      // 每次请求按会话动态解析角色（闭包读 services.roster，不缓存结果）：
+      //   注册表里的 Bot 会话 ⇒ subagent（free_only）；其余 ⇒ main（paid_allowed）；
+      //   roster 不可用/查询抛错 ⇒ unknown（fail-closed，仍 free_only）。
+      roleOf: (sessionId) => roleOfSession(services.roster, sessionId, sessionMeta(ctx, sessionId)),
+    })
+    services.routing = routing
+    if (routing.installed) {
+      log('[cs-bots] 复杂度路由 hint 注入已就绪（llm/stream → cs-myfree 注册表）')
+    } else if (routing.reason === 'cs-myfree-registry-missing') {
+      // 正常情形：本插件可能先于 cs-myfree 装载。注册表在**每次请求时**重新解析，
+      // 所以 cs-myfree 后装载也能立刻生效 —— 这里只记 info，不当降级故障报。
+      log('[cs-bots] 未发现 cs-myfree 路由注册表（稍后装载亦可生效）→ 暂不注入 hint，cs-myfree 默认 free_only')
+    } else {
+      warn(
+        `[cs-bots] 复杂度路由 hint 未就绪（${routing.reason}）→ 降级：不注入 hint，`
+        + 'cs-myfree 按默认 free_only 走（fail-closed，不影响对话）',
+      )
+    }
+  } catch (error) {
+    services.routing = { installed: false, reason: 'assembly-failed' }
+    warn(`[cs-bots] 复杂度路由装配失败（降级，不影响对话）：${error?.message ?? error}`)
+  }
+
+  // ── PDCA-1：回合钩子（让自审计数真正被推进）─────────────────────────────────
+  installTurnHook(ctx, {
+    warn,
+    reviewer: services.reviewer,
+    metrics: services.metrics,
+    suggest: services.suggest,
+  })
+
   // ── 生命周期收尾：停止定时器，避免进程退出被挂起的 timer 拖住 ────────────────
   // 用官方 ctx.effect（若可用）保证插件卸载时被调用；不可用则退化为不注册。
   const dispose = () => {
@@ -233,6 +454,68 @@ function installBlockingToolGate(ctx, { warn, roster }) {
   }
 }
 
+/**
+ * 按会话判定复杂度路由角色（契约 §6 + P3-fix/P3-fix2）。
+ *
+ * 判定顺序（**先严后宽**，任何一步拿不到证据都停在 `'unknown'` ⇒ free_only）：
+ *   a. `roster.hasSession(sessionId)` 命中（含退役 Bot）⇒ `'subagent'`；
+ *   b. 宿主 session 谱系显示是子代理（`origin === 'subagent'` 或 `parentSession` 非空
+ *      或 `delegationDepth > 0`）⇒ `'subagent'`
+ *      —— **这一条堵的是官方 `spawn_teammate` 子会话的付费泄漏**（它们不在 roster 里）；
+ *   c. 两条查询都拿不到信息（roster 不可用/抛错，或 `sessionMeta` 为 null：无 sessions
+ *      服务、无此会话、查询抛错）⇒ `'unknown'`（fail-closed，保持 free_only）；
+ *   d. 能确认是顶层会话（roster 明确「不是 Bot」且宿主给得出 header 但无谱系字段）
+ *      ⇒ `'main'`（人类主对话 ⇒ 平台层注入 paid_allowed）。
+ *
+ * 为什么 c 这么严：宁可让主对话少拿一次付费授权，也不能让某个子智能体白拿 ——
+ * 两者的代价不对称（前者只是慢/弱，后者是持续花错钱）。
+ *
+ * @param {{ hasSession?: Function, list?: Function, listRetired?: Function } | undefined} roster
+ * @param {string} sessionId
+ * @param {{ origin?: string, parentSession?: string, delegationDepth?: number,
+ *           agentPreset?: string } | null} [meta] `kernel.sessionMeta()` 的结果
+ * @returns {'main'|'subagent'|'unknown'}
+ */
+export function roleOfSession(roster, sessionId, meta) {
+  if (typeof sessionId !== 'string' || sessionId === '') return 'unknown'
+
+  // ── a. 注册表：这是本平台的 Bot ⇒ 子智能体 ──
+  const fromRoster = rosterHasSession(roster, sessionId)
+  if (fromRoster === true) return 'subagent'
+  // roster 不可用 ⇒ 无法确认身份 ⇒ 停在这里（即使下面有谱系也不升级为主对话）
+  if (fromRoster === null) return 'unknown'
+
+  // ── b. 宿主谱系：官方子代理 / 任意带父会话的会话 ⇒ 子智能体 ──
+  if (meta === null || meta === undefined) return 'unknown'
+  if (typeof meta !== 'object') return 'unknown'
+  const isSubagent = meta.origin === 'subagent'
+    || (typeof meta.parentSession === 'string' && meta.parentSession !== '')
+    || (typeof meta.delegationDepth === 'number' && Number.isFinite(meta.delegationDepth) && meta.delegationDepth > 0)
+  if (isSubagent) return 'subagent'
+
+  // ── d. 确认是顶层会话 ⇒ 主对话 ──
+  return 'main'
+}
+
+/**
+ * 查 roster 判定某会话是否 Bot。
+ * @returns {true|false|null} `null` = 查询不可用（无 roster / 无查询能力 / 抛错）
+ */
+function rosterHasSession(roster, sessionId) {
+  if (!roster) return null
+  try {
+    if (typeof roster.hasSession === 'function') return roster.hasSession(sessionId) === true
+    // 老版本 roster（无 hasSession）：退化为扫一遍名录，不因此把 Bot 误判成主对话
+    const list = typeof roster.list === 'function' ? roster.list() : undefined
+    if (!Array.isArray(list)) return null
+    const retired = typeof roster.listRetired === 'function' ? roster.listRetired() : []
+    const rows = [...list, ...(Array.isArray(retired) ? retired : [])]
+    return rows.some((b) => b?.sessionId === sessionId)
+  } catch {
+    return null
+  }
+}
+
 /**
  * 判定一个 agent 是否属于本平台的 Bot。
  *
@@ -309,3 +592,103 @@ function installBotToolTrimmer(ctx, { warn, roster }) {
     warn(`[cs-bots] 注册 agent/created 失败：${error?.message ?? error}`)
   }
 }
+
+/**
+ * PDCA-1：回合钩子 —— 让 reviewer 的「每 N 回合自审」真正被触发。
+ *
+ * 为什么必须自己接：宿主把回合边界写成 session 事件（`turn/start` / `turn/end`），
+ * 但**没有**任何机制会自动调用本平台的 reviewer。此前 reviewer 只暴露
+ * HTTP 端点（`/review/note-turn`），客户端从不调用 ⇒ 计数恒为 0 ⇒ 自审永不到期。
+ * 这等于把 PDCA 的 Check 引擎写死了。
+ *
+ * 本钩子的三条纪律（与 dispatcher 的 fail-open 同源）：
+ *   ① **绝不抛**：钩子内部任何异常只 warn，绝不影响回合本身；
+ *   ② **多路兜底**：优先按 session 事件判断回合边界；拿不到就退化为「每次
+ *      `agent/turn-stopping` 也算一回合」（后者是宿主在回合收尾时发的）；
+ *   ③ **每会话每回合最多记一次**：防事件重投导致计数虚高。
+ */
+function installTurnHook(ctx, { warn, reviewer, metrics, suggest }) {
+  if (typeof ctx.on !== 'function') {
+    warn('[cs-bots] ctx.on 不可用 → PDCA 回合钩子未装（自审计数将不自动推进）')
+    return
+  }
+  if (!reviewer) {
+    warn('[cs-bots] 无 ReviewerService → PDCA 回合钩子未装')
+    return
+  }
+
+  /** sessionId → 最近一次计数的标记（防重复计数） */
+  const lastCounted = new Map()
+
+  /** 从钩子 payload 里取会话 id（多路兜底：可能是字符串或 Session/agent 对象）。 */
+  function sessionIdOf(subject) {
+    if (typeof subject === 'string' && subject.trim() !== '') return subject
+    if (subject && typeof subject === 'object') {
+      const id = subject.id ?? subject.sessionId ?? subject.session?.id
+      if (typeof id === 'string' && id.trim() !== '') return id
+    }
+    return null
+  }
+
+  /** 到期时提一条「自审提醒」记忆建议（L2 全局，无需 scopeId ⇒ 任何场景都合法）。 */
+  function proposeSelfReview(sessionId, out) {
+    try {
+      suggest?.suggest?.({
+        kind: 'memory',
+        layer: 'L2',
+        payload: {
+          content: `【自审提醒】本会话已累计 ${out.turnsSinceLastReview} 回合未自审（阈值 ${out.interval}）。下一次回复前请先自检：目标是否漂移？有无未兑现的承诺？有无过期/阻塞的待办或任务？必要时用 bot_memory_search 检索近期上下文。`,
+          tags: ['self-review', 'pdca'],
+        },
+        reason: `reviewer：会话 ${sessionId} 已 ${out.turnsSinceLastReview} 回合未自审（阈值 ${out.interval}）`,
+        source: 'reviewer',
+        by: sessionId,
+        confidence: 0.8,
+      })
+    } catch (e) {
+      warn(`[cs-bots] PDCA 自审建议提议失败（session=${sessionId}）：${e?.message ?? e}`)
+    }
+  }
+
+  try {
+    // ── 主通道：session 事件（宿主在回合开始/结束时写入 turn/start / turn/end）──
+    ctx.on('session/event', (subject, event) => {
+      try {
+        if (!event || typeof event.type !== 'string') return
+        if (event.type !== 'turn/end' && event.type !== 'turn/start') return
+        const sessionId = sessionIdOf(subject)
+        if (!sessionId) return
+
+        // 用回合序号做幂等：同 session 同一 turn 序号只计一次
+        const turn = Number.isFinite(event.data?.turn) ? event.data.turn : null
+        const key = turn !== null ? `${sessionId}:t${turn}` : null
+        if (key && lastCounted.get(sessionId) === key) return
+        if (key) lastCounted.set(sessionId, key)
+
+        const out = reviewer.noteTurn({ sessionId })
+        if (out.due) proposeSelfReview(sessionId, out)
+        try { metrics?.record?.({ kind: 'turn_end', sessionId, by: sessionId }) } catch { /* 测量失败不影响回合 */ }
+      } catch (error) {
+        warn(`[cs-bots] PDCA 回合钩子处理失败：${error?.message ?? error}`)
+      }
+    })
+
+    // ── 兜底通道：agent 回合收尾（session 事件拿不到时仍有一次计数机会）──
+    // ⚠️ 只在主通道没记过该会话时才计（用 lastCounted 防双计）。
+    ctx.on('agent/turn-stopping', (payload) => {
+      try {
+        const sessionId = sessionIdOf(payload?.session ?? payload?.agent ?? payload)
+        if (!sessionId || lastCounted.has(sessionId)) return
+        lastCounted.set(sessionId, 'fallback')
+        const out = reviewer.noteTurn({ sessionId })
+        if (out.due) proposeSelfReview(sessionId, out)
+        try { metrics?.record?.({ kind: 'turn_end', sessionId, by: sessionId }) } catch { /* */ }
+      } catch (error) {
+        warn(`[cs-bots] PDCA 回合兜底钩子处理失败：${error?.message ?? error}`)
+      }
+    })
+  } catch (error) {
+    warn(`[cs-bots] 注册 PDCA 回合钩子失败：${error?.message ?? error}`)
+  }
+}
+