cs-bots 0.7.5 → 0.9.0

package/src/dispatcher.js

@@ -336,6 +336,8 @@ export function createDispatcher(ctx, config = {}) {
       result,
       // ── 平台扩展字段（§3.5 未列，但对「可读原因」与可审计是必需的）──
       text: draft.text,
+      // t-39 第2批 D：唤醒成本可见。无团队归属时是 null（不猜）。
+      teamId: draft.teamId ?? null,
       updatedAt: at,
       seq: takeSeq(),
     }
@@ -345,14 +347,22 @@ export function createDispatcher(ctx, config = {}) {
     return { wake, durable }
   }
 
-  /** 构造 wake 草稿（此刻尚无终态；`result` 只在 `commit` 时赋值）。 */
-  function draftWake({ target, reason, dedupKey, text, at }) {
+  /**
+   * 构造 wake 草稿（此刻尚无终态；`result` 只在 `commit` 时赋值）。
+   *
+   * `teamId`：唤醒成本可见（t-39 第2批 D）。**不是所有唤醒都属于某个团队**
+   * （例如任务派活、房间广播都可能与团队无关）—— 那种情况一律写 `null`，
+   * 绝不按 target 猜一个团队塞进去：猜出来的数字比没有更糟，它会让
+   * 「每团队唤醒成本」的统计凭空多出一份不属于它的开销。
+   */
+  function draftWake({ target, reason, dedupKey, text, at, teamId }) {
     return {
       id: `wake-${at}-${process.pid.toString(36)}-${takeSeq().toString(36)}`,
       target,
       reason,
       dedupKey,
       text,
+      teamId: teamId ?? null,
       scheduledAt: at,
     }
   }
@@ -449,7 +459,7 @@ export function createDispatcher(ctx, config = {}) {
    */
   function notify(request = {}) {
     const at = now()
-    const { target, reason, dedupKey, text, delayMs } = request
+    const { target, reason, dedupKey, text, delayMs, teamId } = request
     const wakeText = text ?? `[cs-bots 唤醒] ${REASON_TEXT[reason] ?? String(reason)}`
 
     // 每调用一次 = 一次决策，先计数（恒等式 total === sent + skipped + failed + pending 由此成立）。
@@ -462,7 +472,7 @@ export function createDispatcher(ctx, config = {}) {
     }
     if (!WAKE_REASONS.includes(reason)) {
       counters.failed += 1
-      const draft = draftWake({ target, reason: String(reason), dedupKey, text: wakeText, at })
+      const draft = draftWake({ target, reason: String(reason), dedupKey, text: wakeText, at, teamId })
       const { wake, durable } = commit(draft, 'failed', { at, detail: `invalid-reason:${reason}` })
       return { ok: false, result: 'failed', wakeId: wake.id, reason: 'invalid-reason', durable }
     }
@@ -474,7 +484,7 @@ export function createDispatcher(ctx, config = {}) {
       let wakeId
       let durable = probe.writable
       if (last === undefined || at - last >= SKIP_RECORD_INTERVAL_MS) {
-        const draft = draftWake({ target, reason, dedupKey, text: wakeText, at })
+        const draft = draftWake({ target, reason, dedupKey, text: wakeText, at, teamId })
         const committed = commit(draft, 'skipped', { at })
         wakeId = committed.wake.id
         durable = committed.durable
@@ -490,7 +500,7 @@ export function createDispatcher(ctx, config = {}) {
     if (queue.sizeOf(target) >= maxPerTarget) {
       counters.backpressured += 1
       counters.failed += 1
-      const draft = draftWake({ target, reason, dedupKey, text: wakeText, at })
+      const draft = draftWake({ target, reason, dedupKey, text: wakeText, at, teamId })
       // 请求被**拒绝**（而非「受理后没送成」）⇒ 该 dedupKey 尚未被消费，释放它，
       // 队列疏通后上游仍可用同一个 dedupKey 重发。
       if (dedupKey) dedup.keys.delete(dedupKey)
@@ -516,7 +526,7 @@ export function createDispatcher(ctx, config = {}) {
       deferred = notBefore > at
     }
 
-    const draft = draftWake({ target, reason, dedupKey, text: wakeText, at })
+    const draft = draftWake({ target, reason, dedupKey, text: wakeText, at, teamId })
     const entry = { draft, notBefore, keyHeld: Boolean(dedupKey) }
     queue.add(entry)
     if (deferred) counters.deferred += 1
@@ -614,25 +624,74 @@ export function createDispatcher(ctx, config = {}) {
   /**
    * 从 `wakes.jsonl` 读唤醒记录（**读盘，不是读内存** —— 进程重启后仍可审计）。
    *
-   * @param {{ target?: string, limit?: number }} [options]
+   * @param {{ target?: string, teamId?: string, limit?: number }} [options]
+   *        `teamId` 是 t-39 第2批 D 加的：唤醒成本可见（按团队过滤）。
    * @returns {object[]} 终态 Wake 记录（落盘顺序；有 `limit` 时取**最后** limit 条）
    */
   function list(options = {}) {
-    const { target, limit } = options
-    // 先按 limit 取尾，再按 target 过滤 —— 语义是「最近 limit 条里属于该 target 的」。
+    const { target, teamId, limit } = options
+    // 先按 limit 取尾，再按 target / teamId 过滤 —— 语义是「最近 limit 条里属于该 target/team 的」。
     const { rows, bad, total } = readJsonl(wakesFile, limit ? { limit } : {})
-    const filtered = target ? rows.filter((row) => row?.target === target) : rows
+    let filtered = rows
+    if (target) filtered = filtered.filter((row) => row?.target === target)
+    if (teamId) filtered = filtered.filter((row) => row?.teamId === teamId)
     // 坏行**不静默**：作为非枚举属性挂上，调用方可用 `Object.keys` 忽略、也可显式读取。
     Object.defineProperty(filtered, 'bad', { value: bad, enumerable: false })
     Object.defineProperty(filtered, 'total', { value: total, enumerable: false })
     return filtered
   }
 
+  /**
+   * 按团队聚合唤醒成本（t-39 第2批 D）。
+   *
+   * 为什么需要：Boss 要看「哪个团队在消耗唤醒配额」。单看 target 看不出团队归属
+   * （target 是会话 id，团队归属在 `teamId` 上）。
+   *
+   * 只聚合**真正有 teamId 的记录**；`teamId === null` 的（任务派活、房间广播等
+   * 与团队无关的唤醒）单独归入 `teamId: null` 桶，不混进任何团队数字里。
+   *
+   * @param {{ since?: number }} [options] `since` = epoch ms，只统计该时刻之后的记录
+   * @returns {{ since?: number, teams: object[], unassigned: object, total: number }}
+   */
+  function byTeam(options = {}) {
+    const { since } = options
+    const { rows } = readJsonl(wakesFile, { limit: 100_000 })
+    const buckets = new Map()
+    let total = 0
+    for (const row of rows) {
+      const at = row?.scheduledAt ?? row?.at
+      if (since !== undefined && Number.isFinite(since) && Number.isFinite(at) && at < since) continue
+      total += 1
+      const key = row?.teamId ?? null
+      if (!buckets.has(key)) {
+        buckets.set(key, { teamId: key, count: 0, sent: 0, skipped: 0, failed: 0, pending: 0, targets: new Set() })
+      }
+      const b = buckets.get(key)
+      b.count += 1
+      const r = row?.result
+      if (r === 'sent') b.sent += 1
+      else if (r === 'skipped') b.skipped += 1
+      else if (r === 'failed') b.failed += 1
+      else if (r === 'pending') b.pending += 1
+      if (row?.target) b.targets.add(row.target)
+    }
+    const teams = [...buckets.entries()]
+      .filter(([key]) => key !== null)
+      .map(([, b]) => ({ ...b, targets: b.targets.size, targetsList: [...b.targets] }))
+      .sort((a, b) => b.count - a.count)
+    const unassignedEntry = buckets.get(null)
+    const unassigned = unassignedEntry
+      ? { teamId: null, count: unassignedEntry.count, sent: unassignedEntry.sent, skipped: unassignedEntry.skipped, failed: unassignedEntry.failed, pending: unassignedEntry.pending, targets: unassignedEntry.targets.size, targetsList: [...unassignedEntry.targets] }
+      : { teamId: null, count: 0, sent: 0, skipped: 0, failed: 0, pending: 0, targets: 0, targetsList: [] }
+    return { since: since ?? null, teams, unassigned, total }
+  }
+
   return {
     notify,
     flush,
     stats,
     list,
+    byTeam,
     /** 只读诊断：状态目录 / 文件路径 / 是否可写。 */
     paths: { stateDir: stateDirectory, wakesFile },
     /** 状态目录可否持久化；`false` ⇒ 所有返回值都会带 `durable:false`。 */

package/src/index.js

@@ -127,7 +127,14 @@ function applyInner(ctx, config, { log, warn }) {
     // ⚠️ 2026-11-05（P0）：createBoard 必须拿到 settings —— wipLimitPerBot（WIP 上限）
     //   与 requireTriageForReady（Ready 闸门）都从 config.settings 读。只传 stateDir 会让
     //   平台设置对任务板静默失效（永远退回代码内默认值），且用户改了设置看不到任何变化。
-    services.board = createBoard(ctx, { stateDir: config.stateDir, leaseMs: settings.defaultLeaseMs, settings })
+    services.board = createBoard(ctx, {
+      stateDir: config.stateDir,
+      leaseMs: settings.defaultLeaseMs,
+      settings,
+      // 指标旁路（bots04 欠账2）：传**取值函数**而不是实例 ——
+      // metrics 在 L276 才装配，此刻还是 undefined。传函数可规避装配顺序耦合。
+      metrics: () => services.metrics,
+    })
     log(`[cs-bots] BoardService 就绪（stateDir=${services.board.paths?.stateDir ?? '?'}）`)
     // ⚠️ 修复（2026-11-04 测试，P1-4）：expireLeases 之前无任何调用者，
     //   owner 崩溃/失联后任务永久停在 in_progress（连"重启时回收"都不做）。

package/src/kernel.js

@@ -297,6 +297,21 @@ export function hostLlmAvailable() {
  *    sole ordinary message of its own turn."
  * ⇒ 适合「有新活要干」的唤醒。
  *
+ * ⚠️ **`followup` 在 `agent` 对象上，不在 `agents` 服务上** —— 这里极易搞错。
+ *
+ * 写测试替身时，很多人会自然地把 `followup` 挂到假 `agents` 服务上
+ * （像 `create` / `get` / `list` 那样），结果永远拿到 `followup-unsupported`，
+ * 而且报错信息不指向真正的原因。2026-11-11 实测踩过一次，
+ * 排查时还一度以为是 `assertDeliverable` 拦的。
+ *
+ * 正确形状：
+ * ```js
+ * get: (key) => key === 'agents' ? {
+ *   get: (id) => ({ id, sessionId: id, followup(msg) { ... } }),  // ← 挂在这里
+ *   // 不是这里：followup(msg) {}
+ * } : undefined
+ * ```
+ *
  * @param {object} ctx
  * @param {string} sessionId
  * @param {string} text

package/src/room.js

@@ -154,6 +154,18 @@ 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'])
+/** 是否为人类身份（房间转发一律跳过）。 */
+function isHumanId(id) {
+  return typeof id === 'string' && HUMAN_IDS.includes(id)
+}
 /** 房间事件类型集合（审计流可枚举）。 */
 const EVENTS = [
   'room_created',
@@ -186,6 +198,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 +303,55 @@ 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
+}
+
 /** 时间参数归一：缺省 now；支持 ms 数字与 Date。 */
 function normalizeNow(value, where) {
   if (value === undefined || value === null) return Date.now()
@@ -373,7 +442,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,28 +1949,109 @@ 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)
+    let targetSource
+    let noTargetReason
+
+    if (targets !== undefined && targets !== null) {
+      targetList = stringList(targets, 'targets', 'relay')
       if (targetList.length === 0) {
         throw new RoomError(
-          `room.relay：房间 ${room.id} 除发送者（${message.from}）外没有其他成员，且未显式指定 targets`
-          + ' —— 拒绝空转发（静默无操作）',
+          `room.relay：targets 是空数组 —— 拒绝空转发（静默无操作），请显式给出目标或省略该字段走缺省`,
           'ROOM_NO_TARGETS',
-          { roomId: room.id, messageId: mid, from: message.from },
+          { roomId: room.id, messageId: mid },
         )
       }
+      targetSource = 'explicit'
+      // 显式 targets 可能混进人类 —— 剔除，但这是**调用方的错**，如实 warn 不静默
+      const humans = targetList.filter((t) => isHumanId(t))
+      if (humans.length > 0) {
+        warn(`[cs-bots/room] relay 显式 targets 含人类身份 ${humans.join(',')} —— 已剔除（人不可被唤醒）`)
+        targetList = targetList.filter((t) => !isHumanId(t))
+      }
+    } else if (mentionOnly) {
+      // 从消息里解析「被 @ 的人」：mentions 字段 + text 里的 `@id`（与 admission.isAddressed 同口径）
+      const mentioned = collectMentions(message, room.members)
+      targetList = mentioned.filter(wakeable)
+      targetSource = 'mention'
+      if (targetList.length === 0) {
+        targetSource = 'mention-only-no-target'
+        noTargetReason = 'mention-only-no-target'
+      }
     } else {
-      targetList = stringList(targets, 'targets', 'relay')
+      targetList = room.members.filter(wakeable)
+      targetSource = 'broadcast'
       if (targetList.length === 0) {
         throw new RoomError(
-          `room.relay：targets 是空数组 —— 拒绝空转发（静默无操作），请显式给出目标或省略该字段走缺省`,
+          `room.relay：房间 ${room.id} 除发送者（${message.from}）外没有其他可唤醒成员，且未显式指定 targets`
+          + ' —— 拒绝空转发（静默无操作）',
           'ROOM_NO_TARGETS',
-          { roomId: room.id, messageId: mid },
+          { 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}`)
+      }
+      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',
+      }
+    }
+
     for (const t of targetList) {
       if (!room.members.includes(t)) {
         throw new RoomError(
@@ -1992,6 +2142,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

package/src/roster.js

@@ -831,6 +831,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 "关键" 段）。
    *
@@ -1408,6 +1461,7 @@ export function createRoster(ctx, config = {}) {
     hasSession,
     rename,
     retire,
+    setPreset,
     setCwd,
     setPrepareCommand,
     getProfile,

package/src/settings.js

@@ -16,8 +16,8 @@ import { resolve, sep, isAbsolute, join } from 'node:path'
 
 /** 设置项定义：默认值 + 校验。 */
 export const SETTING_SPECS = Object.freeze({
-  /** 任务默认租约时长（ms）：owner claim 后多久未心跳即视为失联。 */
-  defaultLeaseMs: { def: 5 * 60_000, min: 10_000, max: 24 * 60 * 60_000, label: '任务租约默认时长（ms）' },
+  /** 任务默认占用时长（ms）：owner claim 后多久未心跳即视为失联。 */
+  defaultLeaseMs: { def: 5 * 60_000, min: 10_000, max: 24 * 60 * 60_000, label: '任务占用默认时长（ms）' },
   /** 唤醒节流窗口（ms）：同一目标在窗内最多唤醒一次。 */
   throttleMs: { def: 5_000, min: 0, max: 60 * 60_000, label: '唤醒节流窗口（ms）' },
   /** 每目标唤醒队列上限（背压阈值）。 */