dsh-bulletin-dispatch 1.3.19

package/src/features/f0b-session-gc.js

@@ -0,0 +1,427 @@
+/**
+ * **会话回收**：把"平台侧已经不存在的会话"从 `sessions` 表里清掉。
+ *
+ * ## 为什么需要（2026-09-30）
+ *
+ * > *"已认桌的会话，我要是把那个会话删掉，系统和仪表盘能不能也同步删掉？"*
+ *
+ * **原来不能** —— `sessions` 表**只增不减**（只有认桌时往里写，全项目**没有一处 `sessions.delete`**）
+ * ⇒ 你删掉会话，它只是不再跑 `pre-step`，**记录永远留在表里**，
+ * 状态表上**一直列着一个已经不存在的会话**。
+ *
+ * ⚠️ 这是"**表在骗人**"那一类问题 —— 与今天修过的几个同类（状态表漏会话、死配置键）。
+ *
+ * ## 判据（**2026-09-30 实测过，不是推断**）
+ *
+ * | 事实 | 证据 |
+ * |---|---|
+ * | 删会话后 `list()` 里少了它 | 24 → 23 ✅ |
+ * | ⭐ **`stat(被删的 id)` 返回 `undefined`** | ✅ 实测 |
+ * | ⭐ **`stat` 对"没在跑的旧会话"照样认得** | ✅ 被删的那个本来就没在跑，删前答"有"、删后才 `undefined` ⇒ **不会误删历史会话** |
+ *
+ * 平台契约原文：`stat` *"returns the snapshot, or **`undefined` when the session does not exist**"*。
+ *
+ * ## ⭐⭐ 判据的最终形态：**问平台"现在有哪些会话"，而不是自己记**（2026-09-30）
+ *
+ * ### 第一版（错的，已废）：自己维护一个"见过活着"的集合
+ *
+ * 原来是 `stat(id)` + 一个**进程内** `ALIVE` 集合：**只有"曾经查到过它活着"才敢删**。
+ * 想防的是"平台一时查不到 ⇒ 误删"。
+ *
+ * **但它在真环境里坏了**（用户实测）：用户删掉一个会话后，回收**跑了 4 次都没清它**，
+ * 而日志只说"没有发现已消失的会话" —— **看不出为什么**。逐 id 诊断才看清：
+ *
+ * ```
+ * session-2265ab81… → undefined（平台说它不存在）
+ * 但它在"见过活着"的集合里：没有
+ * ⇒ if (!ALIVE.has(id)) continue;   ← 静默跳过
+ * ```
+ *
+ * **根因**：进程**重启过** ⇒ `ALIVE` 重置 ⇒ 那个会话**从未在本进程被"认领"过**
+ * ⇒ **安全阀永久拦着它**。**我为了防误删，造了一个重启后就永远不工作的东西。**
+ *
+ * ### 第二版（现在）：直接问平台要权威名单
+ *
+ * ⭐ **去仓库里找到了现成的**：`ctx.sessionQuery.listSessions()` ——
+ * 契约原文：*"List the **complete logical corpus** with live precedence and cloned headers"*。
+ *
+ * ⇒ **拿它当"现在有哪些会话"的权威名单**，表里不在其中的就删。
+ * **不需要内存集合、不需要持久化、跨重启天然正确**（平台知道真相，我不知道）。
+ *
+ * > ⚠️ `sessionQuery` **在插件根 ctx 上取不到** —— 只能在 **`agent.ctx`** 上拿
+ * > （这一条在 `identity.js` 里已经踩过并记着）。所以扫描要在 **pre-step** 里做，
+ * > 因为那里正好有 `payload.agent.ctx`。
+ *
+ * ## 安全设计（**三条**，第 2 条被上面那次替换掉了）
+ *
+ * | # | 措施 |
+ * |---|---|
+ * | **1** | **只删 `sessions` 表的记录** —— 不动单子、不动取走历史（那些是别的桌的事） |
+ * | **2** | ⭐ **以 `listSessions()` 为准** —— 它不在名单里 ⇒ 平台说它不存在 ⇒ 才删。<br>（拿不到名单时**一条都不删** —— 宁可不清，也不误删） |
+ * | **3** | **不删当前会话自己**（它当然存在，但省一次查询、也避免奇怪的时序） |
+ * | **4** | **节流**（默认 10 分钟一次）：列名单/查询都是异步的，不能每步都全查 |
+ *
+ * ⚠️ **清掉一条记录不会丢东西** —— `sessions` 表是**缓存**（注释里就写着"这是缓存不是权威"）。
+ * 那个会话要是又出现了，下一轮就会**重新认桌、重新写进去**。
+ */
+import { errText } from '../log.js';
+import { listRecords } from '../store.js';
+import { findSessionQuery } from '../identity.js';
+
+/** 本功能的配置键（与 `index.js` 的开关同名）。 */
+export const FEATURE = 'sessionGc';
+
+/**
+ * ⚠️ **只在"拿不到权威名单"时用的兜底**（第一版的机制）。
+ *
+ * 正常路径已经改成"问平台要名单"（见上面那段长注释）。
+ * 这个集合只在**服务不可用**时留个念想 —— 但那时我们**一条都不删**，所以它其实不参与判据了。
+ * 保留它只为了让自测能验"没见过活着就不敢删"这条历史行为。
+ */
+const ALIVE = new Set();
+
+/** ⚠️ **仅供自测**：清掉进程内状态。 */
+export function resetSessionGcForTest() {
+  ALIVE.clear();
+}
+
+/**
+ * 跑一次回收。
+ *
+ * @param {object} p
+ * @param {object} p.sessions `sessions` 表
+ * @param {object} p.sp `sessionPersistence` 服务
+ * @param {string} p.selfSessionId 当前会话（**不删它**）
+ * @param {Function} p.log 诊断日志
+ * @param {Function} p.warn 警告
+ * @returns {Promise<{ checked: number, removed: string[], alive: number }>}
+ */
+export async function sweepSessions({ sessions, sp, sessionQuery, selfSessionId, forget, log, warn }) {
+  const rows = listRecords(sessions).filter(([, r]) => r !== null && typeof r === 'object');
+  const removed = [];
+
+  /**
+   * ⭐ **明确点名"忘掉这个 id"**（2026-09-30 加，为清掉一个孤儿子代理）。
+   *
+   * ## 为什么需要这个入口
+   *
+   * 有个子代理会话（`e0c45fb8…`）—— 它**跑过一次**（所以表里有记录），
+   * 但它是个**空壳**（解压后只有 header），而且**界面到不了它**
+   * （子代理不列在侧栏、搜索也搜不到）。
+   *
+   * ⇒ 删掉它的文件之后，平台**可能**还认得它 ⇒
+   * 常规判据（"平台认得就不删"）会**一直留着那一行**。
+   * ⇒ 给一个**显式的、只删指定 id** 的入口，比等平台自己发现更干脆。
+   *
+   * ⚠️ **只在被明确点名时走这条路**（`forget: ['id']`）—— **绝不用于自动清理**。
+   * 日常那条路仍然是"以 `listSessions()` 的权威名单为准"（见下面）。
+   */
+  if (Array.isArray(forget) && forget.length > 0) {
+    for (const id of forget) {
+      const key = String(id);
+      if (key === selfSessionId) continue;
+      try {
+        await sessions.delete(key);
+        removed.push(key);
+        log('会话回收/按名忘掉', { id: key.slice(0, 24) });
+      } catch (error) {
+        warn('回收：忘不掉（不影响别的）', { id: key.slice(0, 24), error: errText(error) });
+      }
+    }
+    return { checked: 0, removed, alive: ALIVE.size, skipped: [], platformKnows: null };
+  }
+
+  /**
+   * ⭐ **第一步：问平台要"现在有哪些会话"的权威名单。**
+   *
+   * ⚠️ **拿不到名单就一条都不删** —— 宁可不清，也不误删。
+   * （这正是第一版把 `ALIVE` 当判据时犯的错：那个判据在重启后**永远不工作**。）
+   */
+  let known = null;
+  try {
+    const all = await sessionQuery.listSessions();
+    known = new Set(all.map((r) => String(r?.header?.id ?? '')).filter((x) => x !== ''));
+  } catch (error) {
+    warn('回收：拿不到会话名单 ⇒ 这一轮不删任何东西', { error: errText(error) });
+  }
+  if (known === null) {
+    return { checked: 0, removed: [], alive: ALIVE.size, skipped: [], note: '拿不到权威名单，未动任何记录' };
+  }
+
+  /** 顺带把"平台认得、我们表里也有"的记进兜底集合（诊断用）。 */
+  for (const [id] of rows) if (known.has(id)) ALIVE.add(id);
+
+  const skipped = [];
+  let checked = 0;
+
+  for (const [id] of rows) {
+    if (id === selfSessionId) continue;                 // 措施 3：不动自己
+    checked += 1;
+    if (known.has(id)) continue;                        // ⭐ 平台认得它 ⇒ 留着
+
+    /**
+     * ⚠️ **平台不认得它 ⇒ 删**。
+     *
+     * 这里**不再需要"我见过它活着没有"** —— 平台自己的名单就是真相。
+     * （第一版正是在这里静默跳过，导致"重启前删掉的会话永远清不掉"。）
+     */
+    try {
+      await sessions.delete(id);
+      ALIVE.delete(id);
+      removed.push(id);
+    } catch (error) {
+      warn('回收：删不掉（不影响别的）', { id: id.slice(0, 24), error: errText(error) });
+      skipped.push(id);
+    }
+  }
+
+  if (removed.length > 0) {
+    log('会话回收/已清理', {
+      count: removed.length,
+      ids: removed.map((x) => x.slice(0, 24)),
+      note: '平台名单里已经没有它们了',
+    });
+  } else {
+    log('会话回收/检查', {
+      checked,
+      platformKnows: known.size,
+      alive: ALIVE.size,
+      heldBySafety: skipped.length,
+      heldIds: skipped.map((x) => x.slice(0, 24)),
+      note: skipped.length > 0 ? '有几个删不掉（见 warning）' : '表里每一条都还在平台名单里',
+    });
+  }
+  return { checked, removed, alive: ALIVE.size, skipped, platformKnows: known.size };
+}
+
+/**
+ * 装这个功能。
+ *
+ * @param {object} api `{ ctx, config, log, warn, store, onStateChanged }`
+ */
+export function setup(api) {
+  const { ctx, config, log, warn, store } = api;
+  const sessions = store.tables.sessions;
+  const intervalMs = Number.isFinite(Number(config.sweepIntervalMs))
+    ? Math.max(0, Number(config.sweepIntervalMs))
+    : 600_000;
+  /** 上次全查的时间（节流用）。 */
+  let lastSweep = 0;
+  /** 正在跑（防止两轮重叠）。 */
+  let running = false;
+  /** `sessionPersistence`（由下面的 `inject` 填上；没就位时就是 undefined）。 */
+  let sp;
+  /** ⚠️ 诊断用：这个实例的 pre-step 有没有被调过（只打一次）。 */
+  let sawFirstCall = false;
+  /**
+   * ⚠️ **最近一次在 pre-step 里看到的 `sessionQuery`**。
+   *
+   * 为什么留这一手：诊断工具 `sweep_sessions` 是在**工具调用**里跑的，
+   * 那里**未必有 `agent.ctx`** ⇒ 拿不到 `sessionQuery`。
+   * 而它每次 pre-step 都会被看到 ⇒ **记住一份**，工具就能用。
+   */
+  let lastSessionQuery;
+
+  /**
+   * 试着跑一次（**节流 + 单飞**）。
+   *
+   * ⚠️ 列名单是**异步**的 ⇒ 不能每步都全查。
+   * 挂在 pre-step 上只是为了"**每轮顺手看一眼**"，真正全查由 `sweepIntervalMs` 控制。
+   *
+   * ⚠️⚠️ **`sessionQuery` 必须从 `agent.ctx` 拿**（不是插件根 ctx）——
+   * 这一条在 `identity.js` 里已经踩过并记着。
+   */
+  function maybeSweep(sessionId, sessionQuery) {
+    if (intervalMs === 0) return;                       // 0 = 关掉（配置可关）
+    if (sessionQuery === undefined) return;             // 拿不到名单服务 ⇒ 下次再说
+    if (running) return;
+    const now = Date.now();
+    if (now - lastSweep < intervalMs) return;
+    running = true;
+    lastSweep = now;
+    /**
+     * ⚠️ **留痕**（2026-09-30 加）：排查"回收到底有没有跑"时，
+     * 原来只有"跑完"的日志 ⇒ **分不清"没被调度"和"被调度了但正在跑"**。
+     * （同一类"静默"问题本项目踩过很多次：认桌/检查 那行就是这么加的。）
+     */
+    log('会话回收/开始全查', { intervalMs, rows: listRecords(sessions).length });
+    void sweepSessions({ sessions, sp, sessionQuery, selfSessionId: sessionId, log, warn })
+      .then((r) => {
+        // ⭐ 删了东西 ⇒ 喊一声让状态表跟上（与"认桌落库"走同一条通路）
+        if (r.removed.length > 0) api.onStateChanged?.('会话回收');
+      })
+      .catch((error) => warn('会话回收整体失败（已忽略）', { error: errText(error) }))
+      .finally(() => { running = false; });
+  }
+
+  /**
+   * ⚠️ 用 **`inject` 拿服务**（不是 `ctx.get`）—— 这一条被误判过两次，
+   * 详见 `进度与待办.md` §二之八之六：`ctx.get` 在"插件刚挂载那一刻"取不到任何服务。
+   */
+  ctx.effect(() => ctx.inject(['sessionPersistence'], (sctx) => {
+    sp = sctx.sessionPersistence;
+    log('会话回收/服务已就位', {
+      intervalMs,
+      /**
+       * ⚠️⚠️ **把"我到底收到什么 config"整个打出来**（2026-09-30）。
+       *
+       * 现象：三份 `cordis.patch.yml`（源码 / profile junction / live 代际）**都写着 `60000`**，
+       * 而这个日志报 `intervalMs = 600000` ⇒ **加载器传给插件的 config 不是我 patch 里那份**。
+       * ⇒ 不再猜"是加载器旧了还是我读错了" —— **直接把现场打出来**：
+       *   · `config` 上有没有 `sweepIntervalMs` 这个键
+       *   · 如果有，值是多少
+       *   · 全部键名是什么（看它像不像我那份 patch）
+       */
+      configKeys: Object.keys(config ?? {}),
+      configSweep: config?.sweepIntervalMs,
+      typeofSweep: typeof config?.sweepIntervalMs,
+    });
+  }));
+
+  /** ⚠️ 平级的第二个 effect（**不要嵌套**）—— 监听器和 inject 各管各的。 */
+  ctx.effect(() => ctx.on('agent/pre-step', async (payload, next) => {
+    const decision = await next();
+    try {
+      const id = payload?.agent?.session?.id;
+      /**
+       * ⭐ **`sessionQuery` 只能在 `agent.ctx` 上拿**（插件根 ctx 上没有它）。
+       *
+       * ⚠️⚠️ **而且不能直接点属性** —— 实测报错原文：
+       * `Error: cannot get property "sessionQuery" without inject`
+       * ⇒ Cordis **必须先声明依赖**（`ctx.get(...)` 或 `inject`）。
+       *
+       * **`findSessionQuery()` 正是干这个的**（先 `get()`、不行再点属性）——
+       * 而且 `identity.js` 里早就写着这条坑。**我第一次写这个功能时没照它做，白挨一次。**
+       */
+      const sq = findSessionQuery(payload?.agent?.ctx);
+      if (sq !== undefined) lastSessionQuery = sq;
+      /**
+       * ⚠️ **每个进程的第一次调用必打一条**（2026-09-30 加，为了查一个查不出的问题）。
+       *
+       * 现象：真环境里 `认桌/检查` 每 10 秒都在跑（⇒ pre-step 是活的），
+       * 但回收那条路**一次都没走到**（连"开始全查"都没有）——
+       * 而**同样的代码在隔离环境逐字验过**（`intervalMs=60000` → 全查 → 检查）。
+       * ⇒ 把**决定是否开跑的那几个变量的现场**打出来，**不再靠推断**。
+       */
+      if (!sawFirstCall) {
+        sawFirstCall = true;
+        log('会话回收/首次调度', {
+          hasSessionId: typeof id === 'string' && id !== '',
+          serviceReady: sp !== undefined,
+          hasSessionQuery: sq !== undefined,
+          intervalMs,
+          configSweep: config?.sweepIntervalMs,
+          running,
+          lastSweep,
+        });
+      }
+      if (typeof id === 'string' && id !== '') maybeSweep(id, sq);
+    } catch (error) {
+      warn('会话回收的调度出错（已忽略）', { error: errText(error) });
+    }
+    return decision;
+  }));
+
+  /**
+   * 自测/诊断用：**立刻**跑一次（绕过节流）。
+   *
+   * ⚠️ 为什么要暴露它：真环境里回收"跑了但没删"，而**日志看不出为什么**
+   * —— 分不清是"`stat` 说它还活着"、"没见过它活着"、还是"删失败了"。
+   * ⇒ 给一个能**当场问**的入口，比读日志猜强。
+   */
+  function sweepNow(selfSessionId, sessionQuery, forget) {
+    const sq = sessionQuery ?? lastSessionQuery;
+    if (sq === undefined) return Promise.resolve({ checked: 0, removed: [], alive: ALIVE.size, skipped: [], note: '拿不到 sessionQuery（它只在 agent.ctx 上）' });
+    return sweepSessions({ sessions, sp, sessionQuery: sq, selfSessionId, forget, log, warn });
+  }
+
+  /** 诊断用：现在"见过活着"的集合 + 节流状态。 */
+  function gcState() {
+    return {
+      alive: [...ALIVE],
+      aliveCount: ALIVE.size,
+      intervalMs,
+      lastSweep,
+      running,
+      serviceReady: sp !== undefined,
+      hasSessionQuery: lastSessionQuery !== undefined,
+    };
+  }
+
+  /**
+   * ⭐ **诊断工具**（2026-09-30 加）。
+   *
+   * 为什么需要：真环境里回收"跑了但没删"，**读日志看不出为什么** ——
+   * 分不清"`stat` 说它还活着"、"没见过它活着"、还是"删失败了"。
+   * ⇒ 给一个**能当场问**的入口。
+   */
+  ctx.effect(() => ctx.inject(['tools'], (tctx) => tctx.tools.register({
+    name: 'sweep_sessions',
+    description:
+      '【诊断】立刻跑一次会话回收（绕过节流），报告：查了几个、删了几个、'
+      + '以及"见过活着"的会话集合。用来回答"我的会话回收到底有没有在工作"。'
+      + '⚠️ 会真的删除记录（但只删"平台侧已确认不存在"的那些）。',
+    parameters: {
+      type: 'object',
+      properties: {
+        dry: { type: 'boolean', description: '只报告不删（默认 false）' },
+        stats: { type: 'boolean', description: '逐 id 报平台名单里有没有它' },
+        forget: {
+          type: 'string',
+          description: '⭐ **明确点名要忘掉的会话 id**（逗号分隔）—— 只删这些，'
+            + '走的是"人明确要求"而不是自动判据。用来清掉"平台可能还认得、但确定不要了"的记录。',
+        },
+      },
+      required: [],
+      additionalProperties: false,
+    },
+    output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: String(v) }] },
+    execute: async (args, exec) => {
+      const out = [];
+      const st = gcState();
+      out.push(`节流：${st.intervalMs} ms ｜ 上次全查：${st.lastSweep === 0 ? '（还没跑过）' : `${new Date(st.lastSweep).toISOString().slice(11, 19)}Z`}`);
+      out.push(`拿到 sessionQuery：${st.hasSessionQuery} ｜ sessionPersistence：${st.serviceReady}`);
+
+      /**
+       * ⭐ **先要权威名单** —— 判据是"平台名单里有没有它"，不再是"我见没见过它活着"。
+       */
+      let known = null;
+      const sq = findSessionQuery(exec?.agent?.ctx) ?? lastSessionQuery;
+      if (sq !== undefined) {
+        try {
+          const all = await sq.listSessions();
+          known = new Set(all.map((r) => String(r?.header?.id ?? '')).filter((x) => x !== ''));
+        } catch (error) { out.push(`⚠️ 列名单失败：${errText(error)}`); }
+      }
+      out.push(known === null
+        ? '**平台名单：拿不到**（⇒ 按设计，这一轮不会删任何东西）'
+        : `**平台名单里有 ${known.size} 个会话**`);
+
+      const rows = listRecords(sessions).map(([id]) => id);
+      out.push('');
+      out.push(`我的记录表里有 ${rows.length} 条：`);
+      if (known !== null && (args?.stats === true || args?.dry === true)) {
+        for (const id of rows) {
+          out.push(`  · \`${id.slice(0, 26)}…\` ${known.has(id) ? '（平台认得 ✅）' : '（**平台说没有** ⇒ 该清）'}`);
+        }
+      }
+
+      if (args?.dry !== true) {
+        out.push('');
+        out.push('**跑一次全查**：');
+        const forget = typeof args?.forget === 'string' && args.forget !== ''
+          ? args.forget.split(',').map((s) => s.trim()).filter(Boolean)
+          : undefined;
+        if (forget !== undefined) out.push(`  ⚠️ 这次是**按名忘掉**：${forget.join(', ')}`);
+        const r = await sweepNow(exec?.agent?.session?.id, sq, forget);
+        out.push(`  查了 ${r.checked} 个 · 删了 ${r.removed.length} 个${r.removed.length > 0 ? `：${r.removed.map((x) => `\`${x.slice(0, 22)}…\``).join('、')}` : ''}`);
+        if (typeof r.note === 'string') out.push(`  说明：${r.note}`);
+        if (Array.isArray(r.skipped) && r.skipped.length > 0) out.push(`  ⚠️ 没删掉的：${r.skipped.length} 个`);
+        out.push(`  跑完"见过活着"的集合：${gcState().aliveCount} 个`);
+      }
+      return out.join('\n');
+    },
+  })));
+
+  return { sweepNow, gcState };
+}

package/src/features/f1-propose-rename.js

@@ -0,0 +1,214 @@
+/**
+ * 「提议改名」—— 2026-09-30 的 **方案 A：提议 + 用户点头才改**。
+ *
+ * ## 为什么不是"AI 自己改"（哪怕技术上完全做得到）
+ *
+ * 平台**确实**提供了这个能力（实测查到的服务契约）：
+ *   `ctx.sessionTitle.rename(session, title)` —— **真服务，不是 `@Remote`，插件直接可调**。
+ * （另一条 `ctx.sessionController.rename()` 是 `@Remote`，那是**给 UI 的**，即用户手动改名走的路。）
+ *
+ * 但能改 ≠ 该自己改。两条风险：
+ *   ① **会覆盖用户起的名字** —— 会话里所有 AI 都能改标题；
+ *   ② **任何一张桌都能改任意会话的名字**，包括别的桌的。
+ * 而办公室既有规矩是「**动别的桌子之前要先问用户**」——
+ * **标题记录的是"这张会话属于谁"，它是用户的东西，不是插件的。**
+ *
+ * ## 所以本功能只做两件事
+ *
+ * 1. **认不出桌时，提议一次**（写进系统提示；只在"标题没有 `NN-` 前缀"时出现，
+ *    而且**只提议一次** —— 用户不理会就不再唠叨）；
+ * 2. 提供 **`set_session_title` 工具** —— **AI 只在明确同意后**才调用它。
+ *
+ * ⚠️ **已经有 `NN-` 前缀的会话一个字都不提** —— 绝不覆盖用户已经起好的名字。
+ *
+ * ## ⚠️ 一个硬事实（2026-09-30）
+ *
+ * > **"开新会话不能直接改名，要先发一条消息产生真实会话之后我才能手动改。"**
+ *
+ * ⇒ 所以"平台先给自动标题、用户后改名"是**必然顺序**。
+ * ⇒ 这条提议是**这个缺口的补丁**：AI 可以在用户同意后**当场**改名，不用用户去点。
+ * ⇒ 而且**名字建议也不是瞎猜** —— 它从"这个会话最可能在干哪张桌的活"推：
+ *    `cwd` 能对上某张桌的工作区 ⇒ 用那张桌的名字；否则用**最近在改的文件路径**推。
+ */
+import { deskFromTitle, deskLabel, isResolvedDesk, lookupDesk, rememberDesk } from '../identity.js';
+import { errText } from '../log.js';
+
+/** 本功能的配置键（与 `index.js` 的开关同名）。 */
+export const FEATURE = 'proposeRename';
+
+/**
+ * `systemPrompt.section()` 的排序位。
+ *
+ * ⚠️ **`order` 是必填的**（服务契约 `PromptSection.order: number`），
+ * 忘了传会抛错。用一个小正数：排在"身份/人设"之后、具体工具说明之前。
+ */
+const SECTION_ORDER = 400;
+
+/**
+ * 装配"提议改名"。
+ *
+ * @param {object} api 共享运行环境（见 `index.js`）
+ * @returns {() => void} 卸载函数
+ */
+export function setup(api) {
+  const { ctx, config, log, warn, store } = api;
+  const sessions = store.tables.sessions;
+  const deskNames = config.deskNames ?? {};
+
+  /**
+   * "这个会话提过了"的记账。
+   *
+   * ⚠️⚠️ **两个坑都踩过（2026-09-30 发现的）**：
+   *
+   * ① **原来用内存 `Set`** ⇒ 插件重载 / DSH 重启后**忘了** ⇒ 同一个会话**又提一次**。
+   *    **⇒ 落盘记**（`misc` 表，键 `proposed:<sessionId>`）——
+   *    **因为"一直被提示"比不提示更糟**（见 `docs\01` 那一节）。
+   *
+   * ② **原来在"返回文本之前"就 `add()`** ⇒ 万一那次渲染没真的送到模型
+   *    （平台可能为了测量/试渲染而调用 `text()`），**就永久不说了** —— 反向的错。
+   *    **⇒ 改成 `text()` 被调用过一次之后才记账**（保守：宁可多提一次，不可漏提）。
+   *
+   * ⚠️ 顺带：**`misc` 是权威存储，跨重装/重启都在**；它写不上时退回内存集合
+   * （那样最坏是多提一次，可接受）。
+   */
+  const proposedMemory = new Set();
+  const proposalKey = (sessionId) => `proposed:${sessionId}`;
+
+  function alreadyProposed(sessionId) {
+    try {
+      if (store.tables.misc?.get?.(proposalKey(sessionId)) !== undefined) return true;
+    } catch { /* 存储读不了 → 看内存 */ }
+    return proposedMemory.has(sessionId);
+  }
+
+  function markProposed(sessionId) {
+    proposedMemory.add(sessionId);
+    try {
+      store.tables.misc?.put?.(proposalKey(sessionId), { value: new Date().toISOString(), at: Date.now() });
+    } catch (error) {
+      warn('改名提议的记账写不上（最坏是下次再提一次）', { error: errText(error) });
+    }
+  }
+
+  // ── ① 提议（写进系统提示，但**只在没认出桌时**，且只提一次）────────────────
+  ctx.effect(() => ctx.inject(['systemPrompt'], (pctx) => pctx.systemPrompt.section({
+    name: 'bulletin-dispatch:propose-rename',
+    order: SECTION_ORDER,
+    text: (context) => {
+      try {
+        const agent = context?.agent;
+        const sessionId = agent?.session?.id;
+        if (typeof sessionId !== 'string' || sessionId === '') return '';
+        // ⭐ **先查"当前真相"视图**（同步、进程内），没有才查权威存储。
+        //    修的就是"注入说桌 02、系统提示还说认不出"那个矛盾：
+        //    视图让**同一轮里所有读者看到同一份**数据。
+        const known = lookupDesk(sessionId) ?? sessions.get(sessionId);
+        const desk = typeof known?.desk === 'string' ? known.desk : undefined;
+        // ⭐ **已经认出桌的会话一个字都不提** —— 绝不覆盖用户起好的名字。
+        if (desk === undefined || isResolvedDesk(desk)) return '';
+        if (alreadyProposed(sessionId)) return '';
+
+        // ⚠️ **不猜桌号**：多张桌共用同一个 cwd（`<工作区>`），
+        //    从会话上**推不出**它属于哪张桌 —— 猜错比不猜更糟。**直接问用户。**
+        const deskList = Object.entries(config.deskNames ?? {})
+          .map(([id, name]) => `\`${id}-${name}\``).join('、');
+        const text = '跨桌投递：这个会话的标题没有桌号前缀，**认不出它属于哪张桌**。\n'
+          + (deskList === '' ? '' : `办公室的桌子有：${deskList}。\n`)
+          + '⚠️ 顺手可以问用户一句"这个会话是哪张桌的"，但**要改名前必须先得到用户同意** —— '
+          + '同意之后才调用 `set_session_title`。**用户不同意就不要改，也不要再问第二次。**\n'
+          + '（`NN-` 前缀是跨桌投递唯一能读出来的桌身份。）';
+        // ⭐ 记账**放在最后**：只有真的要给出这段文本时才记（见上面坑 ②）。
+        markProposed(sessionId);
+        return text;
+      } catch (error) {
+        // fail-open：提示渲染失败绝不影响会话。
+        warn('改名提议渲染失败（已忽略）', { error: errText(error) });
+        return '';
+      }
+    },
+  })));
+
+  // ── ② 工具：AI 在**用户同意后**用它改名 ────────────────────────────────────
+  ctx.effect(() => ctx.inject(['tools'], (tctx) => tctx.tools.register({
+    name: 'set_session_title',
+    description:
+      '把**当前会话**的标题改成「NN-名字」形式（N 是两位桌号），让跨桌投递能认出它属于哪张桌。'
+      + '⚠️ **必须先在对话里把新标题给用户看过、得到用户同意，才能调用本工具** —— '
+      + '标题属于用户，不要自己决定改。'
+      + '前缀 `NN-` 后面可以带数字区分同一张桌的第几个会话（如 `02-环境维护2`）。',
+    parameters: {
+      type: 'object',
+      properties: {
+        title: {
+          type: 'string',
+          description: '新标题，必须形如 `02-环境维护2`（两位数字 + 连字符 + 名字）',
+        },
+      },
+      required: ['title'],
+      additionalProperties: false,
+    },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: String(value) }],
+    },
+    execute: async (args, exec) => {
+      const wanted = String(args?.title ?? '').trim();
+      // ⚠️ 复用**同一个**正则（`identity.js`），避免"写的时候和读的时候规则不一样"。
+      if (!/^\d{2}\s*[-－—–]\s*\S/u.test(wanted)) {
+        throw new Error('标题必须是「两位数字 + 连字符 + 名字」的形式，例如 `02-环境维护2`');
+      }
+      const agent = exec?.agent;
+      const session = agent?.session;
+      if (session === undefined) throw new Error('拿不到当前会话（无法改名）');
+
+      // `sessionTitle` 是**真服务**（不是 @Remote）⇒ 插件可以直接调。
+      // 老写法（`ctx.get(...)` 在根作用域）取不到，所以从 `agent.ctx` 试。
+      const st = findSessionTitle(agent?.ctx) ?? findSessionTitle(ctx);
+      if (st === undefined || typeof st.rename !== 'function') {
+        throw new Error('本运行时没有 sessionTitle.rename（无法改名）—— 请让用户手动改会话标题');
+      }
+      const snap = st.rename(session, wanted);
+      const title = snap?.title ?? wanted;
+      const desk = deskFromTitle(title);
+      const sessionId = String(session?.id ?? '');
+      // ⭐ **改名之后立刻同步身份**（2026-09-30 加 —— 实测发现"改了名插件却不认"）：
+      //    光靠"下一轮重读"也能自愈，但**同一轮里**别的读者可能已经按旧身份算过了
+      //    ⇒ 当场把身份改过来，**不留窗口期**。
+      const record = { desk, title, at: Date.now() };
+      try {
+        sessions.put(sessionId, record);
+      } catch (error) {
+        // 持久层写不上不影响改名本身（下一轮重读会补上）。
+        warn('改名后同步持久层失败（下一轮会重读补上）', { error: errText(error) });
+      }
+      // ⭐ **更重要的一步**：写进"当前真相"视图 ⇒ **同一轮里还没渲染的读者立刻看到**。
+      rememberDesk(sessionId, record);
+      log('改名/已改', { session: sessionId.slice(0, 20), title, desk: deskLabel(desk) });
+      return `已把本会话标题改为「${title}」。`
+        + (isResolvedDesk(desk)
+          ? `跨桌投递已认它为 **${deskLabel(desk)}**（当场生效，不用等下一轮）。`
+          : '（⚠️ 但新标题仍然没有桌号前缀，跨桌投递还是认不出桌。）');
+    },
+  })));
+
+  return () => { /* 监听器/段落由 ctx.effect 的 disposer 管 */ };
+}
+
+/**
+ * 在给定 ctx 上找 `sessionTitle`。
+ *
+ * ⚠️ 与 `sessionQuery` 同样的坑：**插件根作用域不一定取得到**，`agent.ctx` 上才有。
+ * 而且判断"有没有"要 `typeof x.rename === 'function'` ——
+ * **`Object.keys(服务)` 看不到方法**（方法在原型链上）。
+ */
+function findSessionTitle(c) {
+  if (c === undefined || c === null) return undefined;
+  try {
+    const direct = typeof c.get === 'function' ? c.get('sessionTitle') : undefined;
+    if (direct !== undefined && direct !== null) return direct;
+  } catch { /* 换下一个途径 */ }
+  try {
+    if (c.sessionTitle !== undefined && c.sessionTitle !== null) return c.sessionTitle;
+  } catch { /* 放弃 */ }
+  return undefined;
+}