cs-bots 0.8.0 → 0.9.1

package/src/room.js

@@ -154,6 +154,38 @@ const RELAY_MULTIPLIER = 3
 const RELAY_FLOOR = 3
 /** 人类发送者 id（§3.2：`from` 为 sessionId 或 `'user'`）。 */
 const USER = 'user'
+/**
+ * 人类身份全集 —— 与 `teams.js` 的 `HUMAN_IDS` 对齐（`ui` / `user` / `person`）。
+ *
+ * **绝不唤醒人**：人是「看页面的人」，不是会话；`kernel.followup` 对着这些 id 必然失败。
+ * 实测证据（2026-11-11）：`wakes.jsonl` 里 `room-msg:m-1:ui → failed` ——
+ * 缺省广播把 Boss 自己也算成唤醒目标，每次必失败一条。
+ */
+const HUMAN_IDS = Object.freeze(['ui', 'user', 'person'])
+
+/**
+ * **规范用户 id**（2026-11-12 t-40 需求⑤）。
+ *
+ * Boss：「以后要统一一下名称……人=用户=boss=user=我」。
+ * 历史数据里同一个人有三种写法（`ui` 来自页面层、`user` 来自 API 层、`person` 来自早期约定），
+ * 于是「这是谁」在每一处都要判三遍，迟早漏一处。
+ *
+ * 采用**读兼容 + 写统一**，而不是一刀切改写历史：
+ *   - 读：`ui`/`person` 一律视为 `user`（`HUMAN_IDS` 仍然认它们，老数据不会失效）；
+ *   - 写：新写入一律用 `user`。
+ * 这样不破坏历史事件流（append-only，改历史等于伪造），又能让新数据只有一个写法。
+ */
+const CANONICAL_USER = 'user'
+
+/** 是否为人类身份（`ui`/`user`/`person` 都认 —— 读侧兼容）。 */
+function isHumanId(id) {
+  return typeof id === 'string' && HUMAN_IDS.includes(id)
+}
+
+/** 把任意人类写法归一成规范 id `user`；非人类身份原样返回。 */
+function normalizeHumanId(id) {
+  return isHumanId(id) ? CANONICAL_USER : id
+}
 /** 房间事件类型集合（审计流可枚举）。 */
 const EVENTS = [
   'room_created',
@@ -186,6 +218,14 @@ const DEFAULT_SETTINGS = Object.freeze({
   allowBotAutoPost: true,
   maxBotsPerRound: 3,
   relayEnabled: true,
+  // ── 定向唤醒（2026-11-11「唤醒风暴」止血）────────────────────────────────
+  // 缺省 **true**：房间消息**只在被 @ 时**才唤醒成员。
+  //
+  // 为什么缺省要改成「安静」：实测 `wakes.jsonl` 里一条消息产生 3 次唤醒尝试、
+  // 3 次全失败（`room-msg:m-1:ui` + 两个 bot 全 failed）—— 缺省广播「除自己外全部成员」
+  // 既吵又必然失败（`ui` 根本没有会话可唤醒）。改缺省 = 把最吵、最容易失败的路径关掉；
+  // 需要广播的房间显式 `mentionOnly:false` 打开。
+  mentionOnly: true,
 })
 /** `bodyRef` 的合法形态（防路径穿越：只允许 `bodies/<安全文件名>.txt`）。 */
 const BODY_REF_RE = /^bodies\/[A-Za-z0-9._-]+\.txt$/
@@ -283,6 +323,113 @@ function stringList(value, field, where) {
   return out
 }
 
+/**
+ * 从消息里收集「被 @ 的成员 id」（与 `admission.isAddressed` 的 `@id` 解析同口径）。
+ *
+ * 两条来源（取并集）：
+ *   1. `message.mentions` —— 结构化数组，若有则优先
+ *   2. `message.text` 里的 `@id` —— 兜底解析（必须是 word-boundary 后的 `@`，避免误伤 `@bot-2` 当 `@bot`）
+ *
+ * 仅保留 **room.members 里实际存在的** id（非成员被 @ 了也不算唤醒目标）。
+ *
+ * ⚠️ 注意：`message.from` 即使被 @ 了也不进唤醒名单（自己不唤醒自己）。
+ * `HUMAN_IDS`（人类身份）也在 `wakeable()` 里统一过滤，这里不再二次过滤。
+ * @param {object} message
+ * @param {string[]} members
+ * @returns {string[]} 被 @ 的可唤醒成员 id（去重、保序）
+ */
+function collectMentions(message, members) {
+  if (!message || typeof message !== 'object') return []
+  const memberSet = new Set(members)
+  const out = []
+  const seen = new Set()
+
+  // ① 结构化 mentions 数组
+  if (Array.isArray(message.mentions)) {
+    for (const m of message.mentions) {
+      if (typeof m === 'string' && memberSet.has(m) && !seen.has(m)) {
+        seen.add(m)
+        out.push(m)
+      }
+    }
+  }
+
+  // ② 文本里的 @id（与 admission.js 同口径：`@id` 后必须跟非标识符字符或结尾）
+  const text = typeof message.text === 'string' ? message.text : ''
+  if (text) {
+    for (const m of members) {
+      if (seen.has(m)) continue
+      const idx = text.indexOf(`@${m}`)
+      if (idx >= 0) {
+        const after = text.slice(idx + 1 + m.length)
+        if (after === '' || !/[A-Za-z0-9_-]/.test(after[0])) {
+          seen.add(m)
+          out.push(m)
+        }
+      }
+    }
+  }
+  return out
+}
+
+/**
+ * 计算「一条房间消息该唤醒谁」—— **唤醒风暴的唯一真相源**。
+ *
+ * 为什么抽成独立函数（2026-11-12 t-40-B 修复）：
+ * 房间有**两条**唤醒路径，过去各写一份目标计算，于是必然漂移：
+ *   - `room.relay()`（`POST /rooms/relay`）实现了四档规则；
+ *   - `POST /rooms/post`（Bot 用 `bot_room_post`、Boss 用 UI **都走这条**）却是
+ *     裸的 `members.filter((m) => m !== skipSelf)` —— 不看 `mentionOnly`、
+ *     不排除人类 id。实测 6 个房间全设了 `mentionOnly:true`，**一次都没生效**；
+ *     8 成员房间 ⇒ 一条消息 8 次模型调用，其中打给人类 id 的必然失败。
+ *
+ * 所以这里只留**一份**规则，两个调用点都用它。改规则只改这里。
+ *
+ * 四档，**顺序即优先级**（与 relay 原注释一致）：
+ *   ① 显式 targets → 原样采信（剔除人类，并 warn：那是调用方的错）
+ *   ② mentionOnly=true 且 @ 了某人 → 只打给被 @ 的成员（不含发送者/人类）
+ *   ③ mentionOnly=true 但没 @ → **空**（只落消息不唤醒，合法结果，不是错误）
+ *   ④ mentionOnly=false（显式关掉定向）→ 除发送者外的全部成员，**仍排除人类**
+ *
+ * @param {{ members?: string[], settings?: object, from?: string }} room 房间快照
+ * @param {{ from?: string, text?: string, mentions?: string[] }} message 消息
+ * @param {{ targets?: unknown, warn?: (m: string) => void }} [options]
+ *        显式目标（仅 relay 用）；`warn` 注入调用方所在作用域的日志器
+ *        （工厂内部有 `warn`，模块顶层没有 —— 这里显式注入，不靠隐式作用域）
+ * @returns {{ targets: string[], source: 'explicit'|'mention'|'mention-only-no-target'|'broadcast' }}
+ */
+function computeWakeTargets(room, message, options = {}) {
+  const members = Array.isArray(room?.members) ? room.members : []
+  const settings = room?.settings ?? DEFAULT_SETTINGS
+  const mentionOnly = settings.mentionOnly !== false
+  // 发送者自己永远不唤醒（发消息的人不需要被自己的消息叫醒）
+  const sender = message?.from ?? room?.from
+  /** 唤醒排除表：人类一律不算唤醒目标（人没有会话，唤醒必然 agent-not-live）。 */
+  const wakeable = (id) => id !== sender && !isHumanId(id)
+
+  if (options?.targets !== undefined && options?.targets !== null) {
+    let list = stringList(options.targets, 'targets', 'relay')
+    const humans = list.filter((t) => isHumanId(t))
+    if (humans.length > 0) {
+      const say = typeof options.warn === 'function' ? options.warn : () => {}
+      say(`[cs-bots/room] 显式 targets 含人类身份 ${humans.join(',')} —— 已剔除（人不可被唤醒）`)
+      list = list.filter((t) => !isHumanId(t))
+    }
+    return { targets: list, source: 'explicit' }
+  }
+
+  if (mentionOnly) {
+    const mentioned = collectMentions(message, members)
+    const targets = mentioned.filter(wakeable)
+    return targets.length > 0
+      ? { targets, source: 'mention' }
+      : { targets: [], source: 'mention-only-no-target' }
+  }
+
+  // ④ 显式关掉定向才广播 —— 即便如此也不唤醒人类、不唤醒发送者自己
+  return { targets: members.filter(wakeable), source: 'broadcast' }
+}
+
 /** 时间参数归一：缺省 now；支持 ms 数字与 Date。 */
 function normalizeNow(value, where) {
   if (value === undefined || value === null) return Date.now()
@@ -373,7 +520,7 @@ function normalizePurpose(value, where = 'createRoom') {
 
 /** `settings` 单个开关校验（按键分派；未知键抛错 —— 拒绝写入「怎么写都不会生效」的配置）。 */
 function normalizeSettingValue(key, value, where) {
-  if (key === 'allowBotAutoPost' || key === 'relayEnabled') {
+  if (key === 'allowBotAutoPost' || key === 'relayEnabled' || key === 'mentionOnly') {
     if (typeof value !== 'boolean') {
       throw new RoomError(
         `room.${where}：settings.${key} 必须是布尔值，收到 ${JSON.stringify(value)}`,
@@ -1880,25 +2027,93 @@ export function createRoom(ctx, config = {}) {
     const message = requireMessage(room.id, mid, 'relay')
     const actor = optionalString(byId, 'byId', 'relay')
 
+    // ══ 目标计算（2026-11-11「唤醒风暴」止血）═══════════════════════════════
+    // 四档，**顺序即优先级**：
+    //   ① 显式给了 targets  → 原样采信（调用方说了算；仍强制排除人类 id）
+    //   ② mentionOnly=true 且消息 @ 了某人 → 只打给被 @ 的成员（不含发送者/人类）
+    //   ③ mentionOnly=true 但没 @      → **只落消息，不唤醒任何人**（relayed:0）
+    //   ④ mentionOnly=false（显式关掉定向）→ 回退「除自己外全部成员」，但仍排除人类
+    //
+    // 为什么③不抛错：「只记录不打扰」是合法结果（Boss 只是同步信息，不需要谁被叫醒）。
+    // 抛错会把「安静」变成「失败」，页面反而要处理异常 —— 那是更差的设计。
+    const settings = room.settings ?? DEFAULT_SETTINGS
+    const mentionOnly = settings.mentionOnly !== false
+    /** 唤醒排除表：人类一律不算唤醒目标（见 HUMAN_IDS 注释的实测证据）。 */
+    const wakeable = (id) => id !== message.from && !isHumanId(id)
     let targetList
-    if (targets === undefined || targets === null) {
-      targetList = room.members.filter((m) => m !== message.from)
-      if (targetList.length === 0) {
-        throw new RoomError(
-          `room.relay：房间 ${room.id} 除发送者（${message.from}）外没有其他成员，且未显式指定 targets`
-          + ' —— 拒绝空转发（静默无操作）',
-          'ROOM_NO_TARGETS',
-          { roomId: room.id, messageId: mid, from: message.from },
-        )
+    let targetSource
+    let noTargetReason
+
+    // 规则统一在 computeWakeTargets（t-40-B）：与 `POST /rooms/post` 共用同一份，
+    // 避免两条唤醒路径各写一套而再度漂移。
+    const decided = computeWakeTargets(room, message, { targets, warn })
+    targetList = decided.targets
+    targetSource = decided.source
+    if (targetSource === 'mention-only-no-target') noTargetReason = 'mention-only-no-target'
+    // 显式 targets 给了空数组 ⇒ 调用方契约违反，抛错（computeWakeTargets 只管剔除人类）
+    if (targetSource === 'explicit' && Array.isArray(targets) && targets.length === 0) {
+      throw new RoomError(
+        `room.relay：targets 是空数组 —— 拒绝空转发（静默无操作），请显式给出目标或省略该字段走缺省`,
+        'ROOM_NO_TARGETS',
+        { roomId: room.id, messageId: mid },
+      )
+    }
+    // 广播档但「除发送者外全是人类」⇒ 这是**配置错误**（没有 bot 可广播），抛错比静默诚实。
+    // 注意：mention 档的空结果不算错（③「只记录不打扰」是合法结果），二者不能混。
+    if (targetSource === 'broadcast' && targetList.length === 0) {
+      throw new RoomError(
+        `room.relay：房间 ${room.id} 除发送者（${message.from}）外没有其他可唤醒成员，且未显式指定 targets`
+        + ' —— 拒绝空转发（静默无操作）',
+        'ROOM_NO_TARGETS',
+        { roomId: room.id, messageId: mid, from: message.from },
+      )
+    }
+
+    // ── ③「没 @ 到谁」：合法空转发 —— 记事件、返回 relayed:0，**不抛错** ──────
+    // 必须在后台账之前分流：否则每次安静发言都吃掉一次 relayLimit 配额。
+    if (targetList.length === 0) {
+      const at0 = normalizeNow(now, 'relay')
+      appendRoomEvent(room.id, {
+        type: 'relay',
+        roomId: room.id,
+        rev: room.rev,
+        byId: actor ?? null,
+        at: at0,
+        messageId: mid,
+        targets: [],
+        attempted: 0,
+        limit: room.relayLimit,
+        targetSource,
+        reason: noTargetReason ?? 'no-wakeable-target',
+      })
+      let audit0 = { written: true }
+      try {
+        appendRoomEvent(room.id, {
+          type: 'relay_result',
+          roomId: room.id,
+          rev: room.rev,
+          byId: actor ?? null,
+          at: at0,
+          messageId: mid,
+          deliveries: [],
+        })
+      } catch (error) {
+        audit0 = { written: false, reason: `relay-result-append-failed:${error?.message ?? error}` }
+        diagnostics.relayResultAppendFailures += 1
+        warn(`[cs-bots/room] 转发结果事件写入失败（投递已发生）：${audit0.reason}`)
       }
-    } else {
-      targetList = stringList(targets, 'targets', 'relay')
-      if (targetList.length === 0) {
-        throw new RoomError(
-          `room.relay：targets 是空数组 —— 拒绝空转发（静默无操作），请显式给出目标或省略该字段走缺省`,
-          'ROOM_NO_TARGETS',
-          { roomId: room.id, messageId: mid },
-        )
+      return {
+        ok: true,
+        roomId: room.id,
+        messageId: mid,
+        relayed: 0,
+        attempted: 0,
+        limit: room.relayLimit,
+        remaining: Math.max(0, room.relayLimit - (relayCounts.get(relayKey(room.id, mid)) ?? 0)),
+        deliveries: [],
+        audit: audit0,
+        targetSource,
+        reason: noTargetReason ?? 'no-wakeable-target',
       }
     }
 
@@ -1992,6 +2207,7 @@ export function createRoom(ctx, config = {}) {
       remaining: Math.max(0, limit - (relayCounts.get(rkey) ?? 0)),
       deliveries,
       audit,
+      targetSource,
     }
     if (failed.length > 0) {
       result.reason = failed
@@ -2153,6 +2369,14 @@ export function createRoom(ctx, config = {}) {
     leave,
     post,
     relay,
+    /**
+     * 计算「这条消息该唤醒谁」（t-40-B）。
+     * 暴露给 `POST /rooms/post` 复用，保证两条唤醒路径共用同一份规则；
+     * 纯函数、不落盘、不唤醒，调用方自己决定要不要投递。
+     * 绑定本实例的 `warn`，这样 HTTP 路径的告警与 relay 走同一个 logger。
+     */
+    computeWakeTargets: (room, message, options = {}) =>
+      computeWakeTargets(room, message, { ...options, warn }),
     readBody,
     listMessages,
     // DESIGN-v2 ①：房间配置 / 归档 / 硬删 / 成员角色（签名见 DESIGN 契约，勿改名）
@@ -2187,5 +2411,6 @@ export const ROOM_DEFAULT_SETTINGS = Object.freeze({ ...DEFAULT_SETTINGS })
 
 /** 用户（人类）发送者 id（`from` 允许的特殊值）。 */
 export const ROOM_USER = USER
+export const ROOM_CANONICAL_USER = CANONICAL_USER
 
 export default createRoom

package/src/roster.js

@@ -100,6 +100,7 @@ const ACTIONS = [
   'create',
   'rename',
   'retire',
+  'purge',
   'set_cwd',
   'claim',
   'release',
@@ -517,6 +518,8 @@ export function createRoster(ctx, config = {}) {
         skipped += 1
         continue
       }
+      // purge 是终态：重放时把它从内存表移除，而不是复活成一条记录
+      if (ev.after.state === 'purged') { bots.delete(ev.botId); events.push(clone(ev)); continue }
       bots.set(ev.botId, clone(ev.after))
       events.push(clone(ev))
     }
@@ -694,7 +697,7 @@ export function createRoster(ctx, config = {}) {
    * @throws {RosterError} 缺字段 / 非法 cwd / 重名 / 会话创建失败 / 事件落盘失败
    */
   async function create(input = {}) {
-    const { name, cwd, label, model, instructions, preset, permission, profile, prepareCommand, byId, now } = input ?? {}
+    const { name, cwd, label, model, instructions, preset, permission, profile, prepareCommand, byId, now, adoptSession } = input ?? {}
     const by = requireString(byId, 'byId', 'create')
     const displayName = requireString(name, 'name', 'create')
     const dir = assertBotCwd(cwd, 'create')
@@ -707,6 +710,28 @@ export function createRoster(ctx, config = {}) {
     // ── 唯一性（校验通过后才动会话，避免「建了会话才发现重名」的资源泄漏）──
     assertNameFree(displayName, undefined, 'create')
 
+    // ── adoptSession：把**已存在的会话**注册成 Bot（2026-11-11 Boss 需求）──
+    // 为什么需要：`create()` 原本只会**新建**会话（`bot-${randomUUID()}`），
+    //   无法接管一个已经在跑、已有上下文的会话。Boss 要把当前会话（带着全部上下文）
+    //   变成可在协作平台派活的 Bot ⇒ 会话 id 必须保持不变。
+    // 语义边界：
+    //   - `adoptSession` 给出时**不建新会话**，注册表直接引用它；
+    //   - 该 sessionId 不能已被别的活跃 Bot 占用（`hasSession` 查重）；
+    //   - 退役 Bot 里的同名 session 不阻止接管（终态已释放名额）。
+    const adopt = optionalString(adoptSession, 'adoptSession', 'create')
+    if (adopt !== undefined) {
+      for (const other of bots.values()) {
+        if (other.state !== 'retired' && other.sessionId === adopt) {
+          throw new RosterError(
+            `roster.create：会话 ${adopt} 已被 Bot「${other.name}」（${other.id}）占用——`
+            + '同一会话不能注册成两个 Bot',
+            'ROSTER_SESSION_TAKEN',
+            { sessionId: adopt, occupiedBy: other.id },
+          )
+        }
+      }
+    }
+
     // ── 同 cwd 提示（非阻塞）：两个活 Bot 共用一个目录会撞 fs 写入边界 ──
     for (const other of bots.values()) {
       if (other.state !== 'retired' && other.cwd === dir) {
@@ -717,29 +742,41 @@ export function createRoster(ctx, config = {}) {
       }
     }
 
-    // ── 会话创建：**唯一能指定 cwd 的路径**（kernel.js:249-287）──
-    const id = `bot-${randomUUID()}`
-    let handle
-    try {
-      handle = await kernel.createSession(ctx, {
-        sessionId: id,
-        cwd: dir,
-        warn,
-        ...(preset !== undefined && preset !== null && preset !== '' ? { agentPreset: String(preset) } : {}),
-      })
-    } catch (error) {
-      throw new RosterError(
-        `roster.create：Bot「${displayName}」的会话创建失败（cwd=${dir}）→ ${error?.message ?? error}`
-        + '——已中止注册（不产生半成品 Bot）',
-        'ROSTER_SESSION_CREATE_FAILED',
-        { name: displayName, cwd: dir, cause: String(error?.message ?? error) },
-      )
-    }
-    const sessionId = pickSessionId(handle, id)
-    if (sessionId !== id) {
-      warn(
-        `[cs-bots/roster] 宿主返回的会话 id（${sessionId}）与请求的（${id}）不同——以宿主返回为准并记入注册表`,
-      )
+    // ── 会话：要么新建，要么接管已有（adoptSession）──
+    //
+    // 新建时这是**唯一能指定 cwd 的路径**（kernel.js:249-287）。
+    // 接管时**不碰会话**：那个会话已经在跑、有自己的 cwd 与上下文，
+    // 我们只是把它登记进注册表 —— 因此 `id` 直接沿用该 sessionId
+    // （不生成 `bot-xxx`），这样 `wake`/任务派活的目标 id 与真实会话对得上。
+    let id
+    let sessionId
+    if (adopt !== undefined) {
+      id = adopt
+      sessionId = adopt
+    } else {
+      id = `bot-${randomUUID()}`
+      let handle
+      try {
+        handle = await kernel.createSession(ctx, {
+          sessionId: id,
+          cwd: dir,
+          warn,
+          ...(preset !== undefined && preset !== null && preset !== '' ? { agentPreset: String(preset) } : {}),
+        })
+      } catch (error) {
+        throw new RosterError(
+          `roster.create：Bot「${displayName}」的会话创建失败（cwd=${dir}）→ ${error?.message ?? error}`
+          + '——已中止注册（不产生半成品 Bot）',
+          'ROSTER_SESSION_CREATE_FAILED',
+          { name: displayName, cwd: dir, cause: String(error?.message ?? error) },
+        )
+      }
+      sessionId = pickSessionId(handle, id)
+      if (sessionId !== id) {
+        warn(
+          `[cs-bots/roster] 宿主返回的会话 id（${sessionId}）与请求的（${id}）不同——以宿主返回为准并记入注册表`,
+        )
+      }
     }
 
     /** @type {Record<string, unknown>} */
@@ -831,6 +868,59 @@ export function createRoster(ctx, config = {}) {
     return commit(current.id, 'rename', by, at, before, next)
   }
 
+  /**
+   * 改预制体（preset）—— 2026-11-11 bots04 补的能力缺口。
+   *
+   * ## 为什么需要它
+   *
+   * `preset` 此前**只能**在 `create()` 时设置，之后没有任何接口能改。
+   * 实测后果：`myfree调研员`（t-36 挂 `agent-not-live` 的那个）preset 为空，
+   * 而空 preset = 走宿主默认预设 = **工具面没有保证**（连 `bot_*` 工具都不一定有）。
+   * 想修只能删掉重建 —— 那会丢掉 sessionId 与全部历史关联，代价过高。
+   *
+   * ## 语义边界
+   *
+   *   - **只改 preset，不重建会话**：已经起来的会话不会被换预设。
+   *     这是诚实的边界 —— 换预设真正生效要等该会话下次启动。
+   *     调用方要能看见这一点，所以返回值里带 `appliesOnNextSession: true`。
+   *   - 退役 Bot 不可改（与 `rename`/`setCwd` 同口径）。
+   *   - CAS：必须带 `expectedRev`。
+   *   - 空串 / null ⇒ 清除 preset（回到宿主默认）。这与 `create` 里
+   *     「不传/空串则不写 preset 字段」是同一口径，避免出现 `preset: ''` 这种半状态。
+   *
+   * @param {{ id: string, preset: string|null, byId: string, expectedRev: number, now?: number }} input
+   * @returns {object} Bot（含 `appliesOnNextSession`）
+   * @throws {RosterError} 不存在 / 已退役 / 缺字段 / rev 不匹配
+   */
+  function setPreset(input = {}) {
+    const { preset, byId, now } = input ?? {}
+    const current = loadForCas(input, 'setPreset')
+    const by = requireString(byId, 'byId', 'setPreset')
+    assertNotRetired(current, 'setPreset', '换预制体')
+
+    const raw = preset === undefined || preset === null ? '' : String(preset).trim()
+    const nextPreset = raw === '' ? undefined : raw
+    if ((current.preset ?? undefined) === nextPreset) {
+      throw new RosterError(
+        `roster.setPreset：Bot ${current.id} 的 preset 已是 ${JSON.stringify(nextPreset ?? null)}——无需变更`,
+        'ROSTER_NOTHING_TO_SET_PRESET',
+        { id: current.id, preset: nextPreset ?? null },
+      )
+    }
+
+    const at = normalizeNow(now, 'setPreset')
+    const before = clone(current)
+    const next = clone(current)
+    next.rev = current.rev + 1
+    if (nextPreset === undefined) delete next.preset
+    else next.preset = nextPreset
+    next.presetUpdatedAt = at
+    next.presetUpdatedBy = by
+    const committed = commit(current.id, 'setPreset', by, at, before, next)
+    // 诚实告知：换 preset 不会立刻影响已存在的会话
+    return { ...committed, appliesOnNextSession: true }
+  }
+
   /**
    * 退役 → **终态，但释放名额**（名字可复用、cwd 可回收；§3.1 "关键" 段）。
    *
@@ -876,6 +966,74 @@ export function createRoster(ctx, config = {}) {
     return committed
   }
 
+  /**
+   * 清理（purge）已退役的 Bot —— **把记录从注册表里真正移走**（2026-11-12 t-40，Boss 要求）。
+   *
+   * 为什么 retire 不够：`retire` 只是把 `state` 置为 `retired`，**记录永远留在注册表里**
+   * （`listRetired()` 能查到、`roster.jsonl` 里一堆测试残留），时间一长注册表就被
+   * 一堆没用的测试 Bot 撑满，管理页看不清到底有哪些在役 Bot。
+   *
+   * 语义边界（必须守住的四条）：
+   *   1. **只能清已退役的** —— 在役 Bot 一律拒绝（`ROSTER_PURGE_ACTIVE`）。
+   *      退役是"我不用它了"，清理是"把这条记录抹掉"；两步分开，避免手滑删在役 Bot。
+   *   2. **只动注册表，绝不动 cwd 目录、绝不动会话** —— Bot 的工作目录里可能有真实产物
+   *      （实测 `/home/ubuntu/output/开发测试001` 里存着 t36 调研报告），
+   *      删目录是不可逆且越权的，本函数**不碰文件系统**。
+   *   3. **事件流仍留档**：往 `roster.jsonl` 追加一条 `purge` 事件（`after` = 清理后的状态），
+   *      重放时据此把该 Bot 从内存表里移除 —— 这样「谁在什么时候清了谁」可审计，
+   *      而不是把历史抹得干干净净。
+   *   4. **幂等**：已清理的再清一次直接跳过（计入 `skipped`），不抛错。
+   *
+   * @param {{ ids?: string[], allRetired?: boolean, reason?: string, byId: string, now?: number }} input
+   *        `ids` 指定要清的 Bot；`allRetired: true` 清全部已退役的（与 `ids` 二选一）
+   * @returns {{ purged: string[], skipped: string[], refused: Array<{id: string, reason: string}> }}
+   */
+  function purge(input = {}) {
+    const { ids, allRetired, reason, byId, now } = input ?? {}
+    const by = requireString(byId, 'byId', 'purge')
+    const note = optionalString(reason, 'reason', 'purge')
+    const at = normalizeNow(now, 'purge')
+
+    let targets = []
+    if (allRetired === true) {
+      for (const b of bots.values()) if (b.state === 'retired') targets.push(b.id)
+    } else if (Array.isArray(ids)) {
+      targets = ids.map((x, i) => requireString(x, `ids[${i}]`, 'purge'))
+    } else {
+      throw new RosterError(
+        'roster.purge：必须给 ids（数组）或 allRetired:true（二选一）—— 拒绝无目标清理',
+        'ROSTER_PURGE_NO_TARGET',
+        {},
+      )
+    }
+
+    const purged = []
+    const skipped = []
+    const refused = []
+    for (const botId of targets) {
+      const current = bots.get(botId)
+      if (!current) { skipped.push(botId); continue }
+      if (current.state !== 'retired') {
+        // 在役 Bot 绝不清理：这是本条 API 最重要的护栏
+        refused.push({ id: botId, reason: `在役（state=${current.state}）—— 先 retire 再 purge` })
+        continue
+      }
+      const before = clone(current)
+      const next = clone(current)
+      next.rev = current.rev + 1
+      next.state = 'purged'
+      next.purgedAt = at
+      next.purgedBy = by
+      if (note !== undefined) next.purgeReason = note
+      // 写事件而不是把它从 jsonl 里抠掉：留档「谁清的、何时清的」
+      commit(botId, 'purge', by, at, before, next)
+      bots.delete(botId)
+      purged.push(botId)
+      info(`[cs-bots/roster] Bot ${botId}（「${current.name}」）已清理出注册表`)
+    }
+    return { purged, skipped, refused }
+  }
+
   /**
    * 换工作目录（**官方完全没有的语义**：teammate 强制继承父 cwd）。
    *
@@ -1408,6 +1566,8 @@ export function createRoster(ctx, config = {}) {
     hasSession,
     rename,
     retire,
+    purge,
+    setPreset,
     setCwd,
     setPrepareCommand,
     getProfile,