From d272d79e21879969b45ac45824d9369de107c8ae Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=94=B3=E6=99=97?= <deepcoldy@gmail.com>
Date: Mon, 1 Jun 2026 16:47:57 +0800
Subject: [PATCH 1/7] =?UTF-8?q?docs(docs-site):=20=E5=8F=91=E5=B8=83?=
 =?UTF-8?q?=E3=80=8C=E5=A4=9A=E8=AF=9D=E9=A2=98=E5=8D=8F=E4=BD=9C=E6=A8=A1?=
 =?UTF-8?q?=E5=BC=8F=E3=80=8D=E7=AB=A0=E8=8A=82=E5=88=B0=E5=A6=99=E7=AC=94?=
 =?UTF-8?q?=E7=AB=99=20+=20=E5=90=8C=E6=AD=A5=E4=BB=93=E5=BA=93=E6=BA=90?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

dogfood 产出（coder 写 + Codex review）的妙笔章节已 publish 到官方站
vkWHeJn1Fn2（PUT 原地更新，URL 不变），同步把 /tmp/botmux-docs/index.html
回写进仓库 docs-site/index.html 保持源一致（功能详解组 multi-bot 之后新增
multi-topic 一节，28 节 NAV 一一对应）。
---
 docs-site/index.html | 53 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/docs-site/index.html b/docs-site/index.html
index 87d853f4..e9b13e62 100644
--- a/docs-site/index.html
+++ b/docs-site/index.html
@@ -448,6 +448,58 @@
 > 相关：用 [角色与团队](#roles) 给每个 bot 设人设和能力标签；用 [一键建会话群](#group) 一句话拉多个 bot 进新群；用 [会话接力](#relay) 把会话搬到协作群。
   </script>
 
+  <script type="text/markdown" data-doc="multi-topic">
+# 多话题协作模式
+
+[多机器人协作](#multi-bot) 的升级版：主 bot（**编排者**）把一个大任务拆成多个**子项目**，在群里**自动开多条话题**，每条话题派一组 bot 并行推进（常见「一个写代码 + 一个 review」），用一张**飞书任务清单**当所有人共享的进度板，最后由主 bot 收齐汇总。一个普通群就是一个并行工作台，你在飞书任务面板一眼看完成度。
+
+## 整体流程
+
+`botmux-orchestrate` skill 教编排者走完整流程：
+
+> 拆子项目 → 提一版「子项目 ↔ bot」分配 → 发给你**一次审批**（可用卡片确认）→ 建飞书任务清单 → 逐个开话题派活 → 收齐回报 → 汇总
+
+一句话串起来：**主 bot 拆解 → 自动开多 topic → 每 topic 派一组 bot（coder + reviewer）→ 飞书任务清单当共享进度板 → 子 bot 用 `botmux report` 回报 → 主 bot 聚合**。
+
+## 派活：botmux dispatch
+
+底层派活靠 `botmux dispatch`：在群里种一条顶层「子项目」话题、把指定 bot @ 进去各起独立会话。返回 JSON（含 `seedMessageId` / `threadRootId`），供编排者登记「子项目 ↔ 话题」的映射。
+
+```bash
+botmux dispatch --title "实现登录模块" \
+  --bot "ou_xxx:Alice:coder" --bot "ou_yyy:Bob:reviewer" \
+  --repo /path/to/repo --brief-file /tmp/brief.md
+```
+
+| 选项 | 说明 |
+|------|------|
+| `--title <t>` | 子项目标题（新开话题时必填） |
+| `--bot <spec>` | 指派的 bot，可重复；spec = `open_id[:名字[:角色]]` |
+| `--brief <text>` / `--brief-file <path>` | 子项目简报：直接给文本，或从文件读取 |
+| `--repo <目录>` | 预设子 bot 工作目录（**绝对路径**，需在子 bot 所在机器上存在），spawn 时直接进入、**免点「选仓库」卡** |
+| `--standby` | **必须配 `--repo`**（且不能与 `--into` 同用）：只发一次 `/repo` 把 bot 拉到指定目录待命、不派简报，之后再用 `--into ... --brief(-file)` 激活 |
+| `--into <话题根id>` | 回到已有话题追加一条（激活待命 bot / 追加协调）；仍需 `--bot`，且非 standby 时必须带 `--brief` 或 `--brief-file` |
+
+## 回报：botmux report
+
+子 bot 在自己的子话题里干完后，用 `botmux report` 把进展 / 完成**发回主编排会话**，主 bot 带完整上下文继续聚合。
+
+```bash
+botmux report "登录模块完成，产出在 src/auth/，已过 review"
+botmux report --content-file /tmp/done.md
+```
+
+> ⚠️ 子话题里**不要直接 @ 主 bot**——本话题没有主 bot 的会话，@ 会另起一个无上下文的新会话。`botmux report` 才会把回报路由回主编排会话所在的话题并 @ 主编排 bot。该命令仅在被 `botmux dispatch` 派活的子项目会话里可用。
+
+## 协作边界
+
+- **同部署的「自家」bot 之间互信** —— 编排者能直接对它们跑 `/repo` 等 operate 级命令（与自家 bot 的对话权限一致）。外部 bot 的授权分两层：`/grant @bot` 只给「对话 / 被 chat-scope 拉起」的 talk-only 权限（不碰 `allowedUsers`、跑不了 operate 级命令）；要让外部 bot 跑 `/repo` 等 operate 级命令，需把它列进 `allowedUsers`。`/introduce` 只负责发现 / 登记 open_id，**不授予任何权限**。
+- 子 bot 须**已在群里、可被 @**（具备 `im:message.group_at_msg.include_bot` 权限）。
+- 一条话题可放多个 bot，它们在话题内**互相 @ 协作**（如 coder 写完 @ reviewer 审）。
+
+> 相关：[多机器人协作](#multi-bot) 是它的基础设施；用 [角色与团队](#roles) 给每个 bot 设人设与能力标签、分清 coder / reviewer 职责；协作群也可用 [一键建会话群](#group) 一键拉起。
+  </script>
+
   <script type="text/markdown" data-doc="tmux">
 # Tmux 会话常驻
 
@@ -1325,6 +1377,7 @@
         ['cards','实时流式卡片'],
         ['web-terminal','Web 终端'],
         ['multi-bot','多机器人协作'],
+        ['multi-topic','多话题协作模式'],
         ['roles','角色与团队'],
         ['tmux','tmux 会话常驻'],
         ['adopt','会话接入 Adopt'],

From d6875d61b4083bc23aba37676bcb8f2a7c1b4af3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=94=B3=E6=99=97?= <deepcoldy@gmail.com>
Date: Mon, 1 Jun 2026 17:01:35 +0800
Subject: [PATCH 2/7] =?UTF-8?q?docs(docs-site):=20=E5=A4=9A=E8=AF=9D?=
 =?UTF-8?q?=E9=A2=98=E5=8D=8F=E4=BD=9C=E6=A8=A1=E5=BC=8F=E7=AB=A0=E8=8A=82?=
 =?UTF-8?q?=E6=94=B9=E5=86=99=E4=B8=BA=E9=9D=A2=E5=90=91=E7=94=A8=E6=88=B7?=
 =?UTF-8?q?=20+=20=E9=99=84=E6=95=88=E6=9E=9C=E6=88=AA=E5=9B=BE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

按申晗反馈：去掉用户无需感知的内部机制（botmux dispatch/report 命令与 flag、
「子话题别 @ 主bot」告警、授权边界细节），改成「怎么用」视角（说需求→确认分配→
看进度/收结果）+ 前置条件 + 一张群内多 bot 协作效果截图（TOS）。已 publish 到
官方站 vkWHeJn1Fn2、live 验证。
---
 docs-site/index.html | 55 +++++++++++++++-----------------------------
 1 file changed, 19 insertions(+), 36 deletions(-)

diff --git a/docs-site/index.html b/docs-site/index.html
index e9b13e62..6769f9dc 100644
--- a/docs-site/index.html
+++ b/docs-site/index.html
@@ -451,54 +451,37 @@
   <script type="text/markdown" data-doc="multi-topic">
 # 多话题协作模式
 
-[多机器人协作](#multi-bot) 的升级版：主 bot（**编排者**）把一个大任务拆成多个**子项目**，在群里**自动开多条话题**，每条话题派一组 bot 并行推进（常见「一个写代码 + 一个 review」），用一张**飞书任务清单**当所有人共享的进度板，最后由主 bot 收齐汇总。一个普通群就是一个并行工作台，你在飞书任务面板一眼看完成度。
+[多机器人协作](#multi-bot) 的升级版：把一个大任务交给主 bot，它会自动把任务拆成多个子项目、在群里开多条话题、给每条话题派一组 bot 并行干活（常见「一个写、一个 review」），用一张飞书任务清单当共享进度板，最后收齐结果汇总给你。一个普通群就变成一个并行工作台。
 
-## 整体流程
+## 怎么用
 
-`botmux-orchestrate` skill 教编排者走完整流程：
+跟主 bot 说一句就行，比如：
 
-> 拆子项目 → 提一版「子项目 ↔ bot」分配 → 发给你**一次审批**（可用卡片确认）→ 建飞书任务清单 → 逐个开话题派活 → 收齐回报 → 汇总
-
-一句话串起来：**主 bot 拆解 → 自动开多 topic → 每 topic 派一组 bot（coder + reviewer）→ 飞书任务清单当共享进度板 → 子 bot 用 `botmux report` 回报 → 主 bot 聚合**。
-
-## 派活：botmux dispatch
-
-底层派活靠 `botmux dispatch`：在群里种一条顶层「子项目」话题、把指定 bot @ 进去各起独立会话。返回 JSON（含 `seedMessageId` / `threadRootId`），供编排者登记「子项目 ↔ 话题」的映射。
+> 「用多话题协作模式，把 ×× 拆成几个子项目并行做」
+>
+> 「你来当编排，协调几个 bot 并行推进这个需求」
 
-```bash
-botmux dispatch --title "实现登录模块" \
-  --bot "ou_xxx:Alice:coder" --bot "ou_yyy:Bob:reviewer" \
-  --repo /path/to/repo --brief-file /tmp/brief.md
-```
+接下来主 bot 会自动：
 
-| 选项 | 说明 |
-|------|------|
-| `--title <t>` | 子项目标题（新开话题时必填） |
-| `--bot <spec>` | 指派的 bot，可重复；spec = `open_id[:名字[:角色]]` |
-| `--brief <text>` / `--brief-file <path>` | 子项目简报：直接给文本，或从文件读取 |
-| `--repo <目录>` | 预设子 bot 工作目录（**绝对路径**，需在子 bot 所在机器上存在），spawn 时直接进入、**免点「选仓库」卡** |
-| `--standby` | **必须配 `--repo`**（且不能与 `--into` 同用）：只发一次 `/repo` 把 bot 拉到指定目录待命、不派简报，之后再用 `--into ... --brief(-file)` 激活 |
-| `--into <话题根id>` | 回到已有话题追加一条（激活待命 bot / 追加协调）；仍需 `--bot`，且非 standby 时必须带 `--brief` 或 `--brief-file` |
+1. 把任务拆成几个子项目，先给你**一版分配方案**（每个子项目派哪些 bot），等你确认；
+2. 你点头后，在群里开多条话题、把对应的 bot 拉进去并行开干；
+3. 建一张**飞书任务清单**当进度板——你在飞书任务里一眼看到每个子项目的进度；
+4. 各组干完后，主 bot 收齐、把结果汇总给你。
 
-## 回报：botmux report
+你全程只需要：**说需求 → 确认分配 → 看进度 / 收结果**。开话题、分工协作、互相回报这些都在 bot 之间自动完成，你不用操心。
 
-子 bot 在自己的子话题里干完后，用 `botmux report` 把进展 / 完成**发回主编排会话**，主 bot 带完整上下文继续聚合。
+## 前置条件
 
-```bash
-botmux report "登录模块完成，产出在 src/auth/，已过 review"
-botmux report --content-file /tmp/done.md
-```
+- 要参与协作的 bot 已经在群里、且能被 @（见 [多机器人协作](#multi-bot)）；
+- 群里开了 OnCall、或给 bot 配好了默认工作目录——这样不用每次告诉它在哪个仓库干活。
 
-> ⚠️ 子话题里**不要直接 @ 主 bot**——本话题没有主 bot 的会话，@ 会另起一个无上下文的新会话。`botmux report` 才会把回报路由回主编排会话所在的话题并 @ 主编排 bot。该命令仅在被 `botmux dispatch` 派活的子项目会话里可用。
+## 效果
 
-## 协作边界
+![多话题协作模式 · 群内多 bot 并行协作](https://magic-builder.tos-cn-beijing.volces.com/uploads/multi-topic-demo.jpg)
 
-- **同部署的「自家」bot 之间互信** —— 编排者能直接对它们跑 `/repo` 等 operate 级命令（与自家 bot 的对话权限一致）。外部 bot 的授权分两层：`/grant @bot` 只给「对话 / 被 chat-scope 拉起」的 talk-only 权限（不碰 `allowedUsers`、跑不了 operate 级命令）；要让外部 bot 跑 `/repo` 等 operate 级命令，需把它列进 `allowedUsers`。`/introduce` 只负责发现 / 登记 open_id，**不授予任何权限**。
-- 子 bot 须**已在群里、可被 @**（具备 `im:message.group_at_msg.include_bot` 权限）。
-- 一条话题可放多个 bot，它们在话题内**互相 @ 协作**（如 coder 写完 @ reviewer 审）。
+> 相关：[多机器人协作](#multi-bot) 是它的基础设施；用 [角色与团队](#roles) 给 bot 设角色（谁写、谁 review）。
 
-> 相关：[多机器人协作](#multi-bot) 是它的基础设施；用 [角色与团队](#roles) 给每个 bot 设人设与能力标签、分清 coder / reviewer 职责；协作群也可用 [一键建会话群](#group) 一键拉起。
-  </script>
+</script>
 
   <script type="text/markdown" data-doc="tmux">
 # Tmux 会话常驻

From 9132c732597b3f24012ede92866d0abd1e00ff30 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=94=B3=E6=99=97?= <deepcoldy@gmail.com>
Date: Mon, 1 Jun 2026 17:33:12 +0800
Subject: [PATCH 3/7] =?UTF-8?q?docs(docs-site):=20=E5=A4=9A=E8=AF=9D?=
 =?UTF-8?q?=E9=A2=98=E5=8D=8F=E4=BD=9C=E6=A8=A1=E5=BC=8F=E5=89=8D=E7=BD=AE?=
 =?UTF-8?q?=E6=9D=A1=E4=BB=B6=E5=8E=BB=E6=8E=89=20OnCall=E2=80=94=E2=80=94?=
 =?UTF-8?q?=E6=B4=BE=E6=B4=BB=E6=97=B6=E4=B8=BB=20bot=20=E7=94=A8=20/repo?=
 =?UTF-8?q?=20=E8=87=AA=E5=8A=A8=E9=85=8D=E5=B7=A5=E4=BD=9C=E7=9B=AE?=
 =?UTF-8?q?=E5=BD=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

申晗指正：OnCall 不是前置条件（它只是省 --repo 的便利）。子话题里的 bot 由主 bot
派活时用 /repo 拉起并配好工作目录，用户无需预先开 OnCall。前置条件只剩「把要协作的
bot 拉进群、可被 @」。
---
 docs-site/index.html | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/docs-site/index.html b/docs-site/index.html
index 6769f9dc..0b86732a 100644
--- a/docs-site/index.html
+++ b/docs-site/index.html
@@ -472,8 +472,7 @@
 
 ## 前置条件
 
-- 要参与协作的 bot 已经在群里、且能被 @（见 [多机器人协作](#multi-bot)）；
-- 群里开了 OnCall、或给 bot 配好了默认工作目录——这样不用每次告诉它在哪个仓库干活。
+想让哪些 bot 参与协作，先把它们拉进这个群、确保能被 @ 到（见 [多机器人协作](#multi-bot)）。其余的——在哪个仓库干活、怎么开话题派活——主 bot 都会自动处理，你不用预先配置（不需要先开 OnCall 之类的）。
 
 ## 效果
 

From 859eefac1d246528990f4f9cb40bd040c06d2eea Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=94=B3=E6=99=97?= <deepcoldy@gmail.com>
Date: Mon, 1 Jun 2026 20:16:28 +0800
Subject: [PATCH 4/7] =?UTF-8?q?feat(report):=20botmux=20report=20=E8=B7=A8?=
 =?UTF-8?q?=E6=9C=BA=E5=99=A8=E5=9B=9E=E6=8A=A5=E2=80=94=E2=80=94=E6=97=A0?=
 =?UTF-8?q?=E6=9C=AC=E5=9C=B0=20registry=20=E6=97=B6=E4=BB=8E=E4=BC=9A?=
 =?UTF-8?q?=E8=AF=9D=E6=8E=A8=E5=AF=BC=E7=BC=96=E6=8E=92=E8=80=85=E5=9D=90?=
 =?UTF-8?q?=E6=A0=87?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

申晗指出真·跨部署（不同人各自机器）的回报没处理好：dispatch 把主编排坐标写在
编排者机器的 orchestrate-dispatch.json，对方 bot 在自己机器读不到→`botmux report`
报「缺少主编排坐标」。同机能跑通只因共用一个 data 目录。

修：新增纯函数 resolveReportTarget——有 registry entry（同机）就用它精确路由（含
thread-scope orchRoot）；没有（跨机）就从子 bot 自己的会话推导：回报发到「子话题所在
chat」(= 编排者的 chat) 顶层、@ 编排者（creatorOpenId）。cmdReport 不再硬要求 registry。
工作目录/授权/跨租户按申晗意见先不碰。含 3 条回归用例。
---
 src/cli.ts            | 50 +++++++++++++++++++++++--------------------
 src/core/dispatch.ts  | 33 ++++++++++++++++++++++++++++
 test/dispatch.test.ts | 22 +++++++++++++++++++
 3 files changed, 82 insertions(+), 23 deletions(-)

diff --git a/src/cli.ts b/src/cli.ts
index c217b5ae..7cff836a 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -26,7 +26,7 @@ import { createInterface } from 'node:readline';
 import { createRequire } from 'node:module';
 import { createHmac, randomBytes } from 'node:crypto';
 import { validateWorkingDir } from './core/working-dir.js';
-import { parseDispatchBotSpec, buildDispatchMessages, buildRepoPrimeText, buildReportContent, eligibleAutoMentionAliases, offTopicSubBotTopic } from './core/dispatch.js';
+import { parseDispatchBotSpec, buildDispatchMessages, buildRepoPrimeText, buildReportContent, eligibleAutoMentionAliases, offTopicSubBotTopic, resolveReportTarget } from './core/dispatch.js';
 import { enableAutostart, disableAutostart, autostartStatus, refreshAutostart } from './autostart.js';
 import { tmuxEnv } from './setup/ensure-tmux.js';
 import { writeBotsJsonAtomic as writeBotsAtomic } from './setup/bots-store.js';
@@ -3516,24 +3516,26 @@ async function cmdReport(rest: string[]): Promise<void> {
   if (!s) { console.error(`未找到 session ${sid}`); process.exit(1); }
   if (!s.larkAppId) { console.error(`session ${sid} 缺少 larkAppId`); process.exit(1); }
 
-  // Resolve the orchestrator coords: its thread/chat from the dispatch registry
-  // (keyed by this sub-bot's thread root), its open_id from this session.
+  // Resolve where the report goes + who to @. Same-machine: the dispatch registry
+  // (keyed by this sub-bot's thread root) carries the orchestrator's exact coords.
+  // CROSS-MACHINE: the orchestrator is on another machine, so its registry isn't
+  // on THIS one — resolveReportTarget falls back to this sub-bot's own session
+  // (report top-level into its chat, @ the dispatcher via creatorOpenId). See
+  // resolveReportTarget / Session.creatorOpenId.
   const regPath = join(resolveDataDir(), 'orchestrate-dispatch.json');
   let reg: Record<string, any> = {};
   try { if (existsSync(regPath)) reg = JSON.parse(readFileSync(regPath, 'utf-8')); } catch { /* */ }
   const entry = s.rootMessageId ? reg[s.rootMessageId] : undefined;
-  // The orchestrator's open_id (sub-bot-app-scoped) is whoever created this
-  // session = the dispatcher. Prefer `creatorOpenId` (set on EVERY creation path,
-  // incl. a no-`/repo` foreign-bot kickoff auto-create where ownerOpenId is
-  // nulled), then `ownerOpenId` (older sessions / `/repo` prime). NEVER
-  // quoteTargetSenderOpenId alone: it tracks the *last* sender who @-ed this
-  // sub-bot, so in a coder+reviewer topic it drifts to the reviewer (observed
-  // live: the coder's report @-ed the reviewer, not the orchestrator). Keep it as
-  // a last-ditch fallback only for pre-existing sessions that predate both fields.
-  const orchOpenId = s.creatorOpenId ?? s.ownerOpenId ?? s.quoteTargetSenderOpenId;
-  if (!entry || !orchOpenId) {
+  const tgt = resolveReportTarget({
+    registryEntry: entry,
+    sessionChatId: s.chatId,
+    creatorOpenId: s.creatorOpenId,
+    ownerOpenId: s.ownerOpenId,
+    quoteTargetSenderOpenId: s.quoteTargetSenderOpenId,
+  });
+  if (!tgt.orchOpenId || !tgt.orchChatId) {
     console.error(
-      '当前会话不是被 botmux dispatch 派活的子项目会话（缺少主编排坐标）。\n' +
+      '找不到主编排坐标：本会话没记录派活者（creatorOpenId/ownerOpenId 都空）或缺 chatId——大概不是被 botmux dispatch 派活的会话。\n' +
       '若确需回报，请改用 `botmux send` 或显式 @ 对应的人/ bot。');
     process.exit(1);
   }
@@ -3543,23 +3545,25 @@ async function cmdReport(rest: string[]): Promise<void> {
   const { sendMessage, replyMessage } = await import('./im/lark/client.js');
   const appId = s.larkAppId!;
 
-  const paras = buildReportContent({ orchOpenId, content });
+  const paras = buildReportContent({ orchOpenId: tgt.orchOpenId, content });
   const postJson = JSON.stringify({ zh_cn: { title: '', content: paras } });
 
   try {
     let msgId: string;
-    if (entry.orchScope === 'chat' || !entry.orchRoot) {
-      // Orchestrator runs at chat scope (普通群整群一个会话) → post to the chat.
-      msgId = await sendMessage(appId, entry.orchChatId, postJson, 'post');
+    if (tgt.orchScope === 'chat' || !tgt.orchRoot) {
+      // Orchestrator at chat scope, or cross-machine fallback → post top-level
+      // into the chat (the sub-topic's chat = the orchestrator's chat).
+      msgId = await sendMessage(appId, tgt.orchChatId, postJson, 'post');
     } else {
-      // Orchestrator lives in its own thread → reply into it so its existing
-      // session (anchored on orchRoot) is the one that receives the report.
-      msgId = await replyMessage(appId, entry.orchRoot, postJson, 'post', true);
+      // Same-machine thread-scope orchestrator → reply into its thread so its
+      // existing context-rich session (anchored on orchRoot) receives the report.
+      msgId = await replyMessage(appId, tgt.orchRoot, postJson, 'post', true);
     }
     console.log(JSON.stringify({
       success: true,
-      reportedTo: entry.orchRoot || entry.orchChatId,
-      orchestrator: orchOpenId,
+      reportedTo: tgt.orchRoot || tgt.orchChatId,
+      orchestrator: tgt.orchOpenId,
+      viaRegistry: !!entry,
       messageId: msgId,
     }));
   } catch (err: any) {
diff --git a/src/core/dispatch.ts b/src/core/dispatch.ts
index 5d38e6e6..1d092034 100644
--- a/src/core/dispatch.ts
+++ b/src/core/dispatch.ts
@@ -193,6 +193,39 @@ export function findSubBotTopic(input: {
   return null;
 }
 
+/**
+ * Resolve where a `botmux report` should go + who to @, so report-back works
+ * even when the orchestrator is on a DIFFERENT machine.
+ *
+ * Same-machine: the dispatch registry (orchestrate-dispatch.json) is local, so
+ * `registryEntry` carries the orchestrator's exact coords (incl. orchRoot for a
+ * thread-scope orchestrator). Cross-machine: the foreign sub-bot's daemon never
+ * wrote that registry, so `registryEntry` is undefined — but everything needed
+ * for the common case is on the sub-bot's OWN session: the report goes top-level
+ * into the chat the sub-topic lives in (= the orchestrator's chat) and @-s the
+ * orchestrator (creatorOpenId, captured from the dispatch @). So we fall back to
+ * `{ orchChatId: sessionChatId, orchScope: 'chat', orchRoot: '' }`.
+ *
+ * orchOpenId prefers `creatorOpenId` (stable, set on every session-creation path
+ * incl. foreign-bot auto-create), then `ownerOpenId`, then the drifting
+ * `quoteTargetSenderOpenId` as a last resort.
+ */
+export function resolveReportTarget(input: {
+  registryEntry?: { orchChatId?: string; orchScope?: string; orchRoot?: string };
+  sessionChatId?: string;
+  creatorOpenId?: string;
+  ownerOpenId?: string;
+  quoteTargetSenderOpenId?: string;
+}): { orchChatId?: string; orchScope: string; orchRoot: string; orchOpenId?: string } {
+  const e = input.registryEntry;
+  return {
+    orchChatId: e?.orchChatId ?? input.sessionChatId,
+    orchScope: e?.orchScope ?? 'chat',
+    orchRoot: e?.orchRoot ?? '',
+    orchOpenId: input.creatorOpenId ?? input.ownerOpenId ?? input.quoteTargetSenderOpenId,
+  };
+}
+
 /**
  * The footgun check shared by `botmux send`'s explicit-mention guard AND its
  * prose `@Name` auto-injection: returns the sub-topic seed if `mentionOpenId` is
diff --git a/test/dispatch.test.ts b/test/dispatch.test.ts
index cf0bd716..ba991bd2 100644
--- a/test/dispatch.test.ts
+++ b/test/dispatch.test.ts
@@ -18,6 +18,7 @@ import {
   findSubBotTopic,
   eligibleAutoMentionAliases,
   offTopicSubBotTopic,
+  resolveReportTarget,
 } from '../src/core/dispatch.js';
 
 describe('parseDispatchBotSpec', () => {
@@ -231,3 +232,24 @@ describe('offTopicSubBotTopic', () => {
     expect(offTopicSubBotTopic({ mentionOpenId: 'ou_subbot', quoteTargetSenderOpenId: 'ou_human', chatId: 'oc_main', registry: {}, activeSeeds: new Set() })).toBeNull();
   });
 });
+
+describe('resolveReportTarget', () => {
+  it('uses the registry entry when present (same-machine, precise thread routing)', () => {
+    const r = resolveReportTarget({
+      registryEntry: { orchChatId: 'oc_orch', orchScope: 'thread', orchRoot: 'om_root' },
+      sessionChatId: 'oc_sub', creatorOpenId: 'ou_orch',
+    });
+    expect(r).toEqual({ orchChatId: 'oc_orch', orchScope: 'thread', orchRoot: 'om_root', orchOpenId: 'ou_orch' });
+  });
+
+  it('CROSS-MACHINE: with no registry entry, derives from the session (chatId + chat-scope)', () => {
+    const r = resolveReportTarget({ registryEntry: undefined, sessionChatId: 'oc_sub', creatorOpenId: 'ou_orch' });
+    expect(r).toEqual({ orchChatId: 'oc_sub', orchScope: 'chat', orchRoot: '', orchOpenId: 'ou_orch' });
+  });
+
+  it('orchOpenId prefers creatorOpenId, then ownerOpenId, then quoteTargetSenderOpenId', () => {
+    expect(resolveReportTarget({ creatorOpenId: 'c', ownerOpenId: 'o', quoteTargetSenderOpenId: 'q' }).orchOpenId).toBe('c');
+    expect(resolveReportTarget({ ownerOpenId: 'o', quoteTargetSenderOpenId: 'q' }).orchOpenId).toBe('o');
+    expect(resolveReportTarget({ quoteTargetSenderOpenId: 'q' }).orchOpenId).toBe('q');
+  });
+});

From f961481cad47452da660346c047a58ae12873bb8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=94=B3=E6=99=97?= <deepcoldy@gmail.com>
Date: Mon, 1 Jun 2026 21:46:40 +0800
Subject: [PATCH 5/7] =?UTF-8?q?feat(session):=20=E6=94=AF=E6=8C=81=20BOTMU?=
 =?UTF-8?q?X=5FQUIET=5FRESTART=20=E9=9D=99=E9=BB=98=E9=87=8D=E5=90=AF?=
 =?UTF-8?q?=EF=BC=8Cdev=20=E9=87=8D=E5=90=AF=E4=B8=8D=E9=87=8D=E6=8E=A8?=
 =?UTF-8?q?=E6=9C=AA=E7=BB=93=E6=9D=9F=E4=BC=9A=E8=AF=9D=E5=8D=A1=E7=89=87?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

本地 dev 反复重启 daemon 时，tmux 后端会在 restore 阶段 eager re-fork 所有
未结束会话，触发 worker_ready 重渲染（PATCH 失败时还会重发）各自的 streaming
卡片，导致飞书话题被反复刷屏。

改动：抽出纯函数 shouldAutoForkOnRestore(backendType, quietRestart)，在 quiet
模式下跳过 tmux 的 eager re-fork——会话照常注册进内存，下一条真实消息再懒
恢复（forkWorker resume → selectSessionBackend 命中存活 tmux 即 isReattach 重连，
不新起 CLI、不丢活儿），与 pty 后端既有行为一致。tmux 会话本身不杀。

开关：BOTMUX_QUIET_RESTART=1（dev 机 ~/.zshrc export 一次）默认静默；生产不设
则 quietRestart=false，gate 退化为原 backendType==='tmux' 判断，行为零变化。
cli.ts 把该 env 显式透传进 pm2 ecosystem（默认 '0'），覆盖 god 进程残留旧值。

Reviewed-by: Codex
---
 src/cli.ts                                 |  6 ++++
 src/config.ts                              |  6 ++++
 src/core/session-manager.ts                | 24 +++++++++++--
 test/session-manager-quiet-restart.test.ts | 41 ++++++++++++++++++++++
 4 files changed, 74 insertions(+), 3 deletions(-)
 create mode 100644 test/session-manager-quiet-restart.test.ts

diff --git a/src/cli.ts b/src/cli.ts
index 7cff836a..4cd2f479 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -252,6 +252,12 @@ function ecosystemConfig(): string {
       // ad-hoc (e.g. `BOTMUX_MEMORY_DIAG_INTERVAL_MS=5000`) when chasing an
       // RSS regression — turned off in master so logs stay quiet.
       BOTMUX_MEMORY_DIAG_INTERVAL_MS: process.env.BOTMUX_MEMORY_DIAG_INTERVAL_MS ?? '0',
+      // Quiet restart (dev): when set, restore registers sessions but skips the
+      // tmux eager re-fork so restarts don't re-push unfinished-session cards.
+      // Pass the shell value through explicitly (default '0') so it overrides
+      // any stale value carried by the long-lived pm2 god daemon — letting an
+      // unset shell var truly turn quiet-restart back off.
+      BOTMUX_QUIET_RESTART: process.env.BOTMUX_QUIET_RESTART ?? '0',
     },
   }));
 
diff --git a/src/config.ts b/src/config.ts
index b2fa0f2b..9e451798 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -54,6 +54,12 @@ export const config = {
     cliId: (process.env.CLI_ID ?? 'claude-code') as import('./adapters/cli/types.js').CliId,
     cliPathOverride: process.env.CLI_PATH,
     backendType: (process.env.BACKEND_TYPE ?? detectDefaultBackend()) as 'pty' | 'tmux',
+    /** Quiet restart (dev): skip the tmux backend's eager re-fork of restored
+     *  sessions on startup, so repeated local restarts don't re-push streaming
+     *  cards for unfinished sessions. Sessions resume lazily on the next
+     *  message. Set `BOTMUX_QUIET_RESTART=1` in the dev shell to default it on;
+     *  production leaves it unset (eager re-attach keeps live cards updating). */
+    quietRestart: ['1', 'true'].includes((process.env.BOTMUX_QUIET_RESTART ?? '').toLowerCase()),
     workingDir: (process.env.WORKING_DIR ?? '~').split(',').map(s => s.trim()).filter(Boolean)[0] || '~',
     workingDirs: (process.env.WORKING_DIR ?? '~').split(',').map(s => s.trim()).filter(Boolean),
     allowedUsers: (process.env.ALLOWED_USERS ?? '').split(',').map(s => s.trim()).filter(Boolean),
diff --git a/src/core/session-manager.ts b/src/core/session-manager.ts
index 906b00c1..df678a23 100644
--- a/src/core/session-manager.ts
+++ b/src/core/session-manager.ts
@@ -527,6 +527,22 @@ export function rememberLastCliInput(ds: DaemonSession, userPrompt: string, cliI
 
 // ─── Session restore ─────────────────────────────────────────────────────────
 
+/**
+ * Whether daemon restore should eagerly re-fork workers to re-attach surviving
+ * tmux panes (which re-renders — or re-posts — each session's streaming card in
+ * its Lark thread). True only on the tmux backend, and suppressed by
+ * quiet-restart (`BOTMUX_QUIET_RESTART=1`) so local-dev restarts don't re-push
+ * cards for unfinished sessions. When suppressed, sessions are still registered
+ * and resume lazily — re-attaching the surviving tmux on the next real message
+ * via `selectSessionBackend` — exactly like the pty backend already does.
+ */
+export function shouldAutoForkOnRestore(
+  backendType: 'pty' | 'tmux',
+  quietRestart: boolean,
+): boolean {
+  return backendType === 'tmux' && !quietRestart;
+}
+
 export async function restoreActiveSessions(activeSessions: Map<string, DaemonSession>): Promise<void> {
   const sessions = sessionStore.listSessions();
   const active = sessions.filter(s => s.status === 'active');
@@ -640,8 +656,10 @@ export async function restoreActiveSessions(activeSessions: Map<string, DaemonSe
     logger.debug(`Registered session ${session.sessionId} (scope: ${scope}, anchor: ${anchor})`);
   }
 
-  // Tmux mode: auto-fork workers for sessions with surviving tmux sessions
-  if (config.daemon.backendType === 'tmux') {
+  // Tmux mode: auto-fork workers for sessions with surviving tmux sessions.
+  // Skipped under quiet-restart (dev) — sessions resume lazily on the next
+  // message instead of re-pushing their cards on every restart.
+  if (shouldAutoForkOnRestore(config.daemon.backendType, config.daemon.quietRestart)) {
     for (const [, ds] of activeSessions) {
       const tmuxName = TmuxBackend.sessionName(ds.session.sessionId);
       if (!TmuxBackend.hasSession(tmuxName)) continue;
@@ -669,7 +687,7 @@ export async function restoreActiveSessions(activeSessions: Map<string, DaemonSe
     }
   }
 
-  logger.info(`Restored ${active.length} session(s)${config.daemon.backendType === 'tmux' ? '' : ', waiting for messages to resume'}`);
+  logger.info(`Restored ${active.length} session(s)${shouldAutoForkOnRestore(config.daemon.backendType, config.daemon.quietRestart) ? '' : ', waiting for messages to resume'}`);
 }
 
 /**
diff --git a/test/session-manager-quiet-restart.test.ts b/test/session-manager-quiet-restart.test.ts
new file mode 100644
index 00000000..02be77cd
--- /dev/null
+++ b/test/session-manager-quiet-restart.test.ts
@@ -0,0 +1,41 @@
+/**
+ * Quiet-restart gate for daemon restore.
+ *
+ * On restart the tmux backend eagerly re-forks every active session to
+ * re-attach its surviving tmux pane — which re-renders (or re-posts) the
+ * session's streaming card in the Lark thread. For local dev, repeated
+ * restarts spam those cards for unfinished sessions. `BOTMUX_QUIET_RESTART=1`
+ * suppresses the eager re-fork: sessions are still registered in memory and
+ * resume lazily (re-attaching the surviving tmux) on the next real message,
+ * exactly like the PTY backend already does. This pins that gate decision.
+ */
+import { describe, it, expect, vi } from 'vitest';
+
+vi.mock('../src/bot-registry.js', () => ({
+  getBot: () => ({ config: { workingDir: '~' } }),
+  getAllBots: () => [],
+}));
+
+vi.mock('../src/config.js', () => ({
+  config: {
+    daemon: { workingDir: '~', workingDirs: ['~'] },
+    session: { dataDir: '/tmp/botmux-test' },
+  },
+}));
+
+import { shouldAutoForkOnRestore } from '../src/core/session-manager.js';
+
+describe('shouldAutoForkOnRestore', () => {
+  it('auto-forks on the tmux backend when quiet-restart is off (production default)', () => {
+    expect(shouldAutoForkOnRestore('tmux', false)).toBe(true);
+  });
+
+  it('suppresses the eager re-fork on tmux when quiet-restart is on (dev restore stays silent)', () => {
+    expect(shouldAutoForkOnRestore('tmux', true)).toBe(false);
+  });
+
+  it('never eagerly forks on the pty backend — it is already lazy', () => {
+    expect(shouldAutoForkOnRestore('pty', false)).toBe(false);
+    expect(shouldAutoForkOnRestore('pty', true)).toBe(false);
+  });
+});

From c955cbd78c9c751a593f3e6ee536afde1ca16538 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=94=B3=E6=99=97?= <deepcoldy@gmail.com>
Date: Tue, 2 Jun 2026 02:52:46 +0800
Subject: [PATCH 6/7] =?UTF-8?q?feat(identity):=20<sender>=20=E5=90=8D?=
 =?UTF-8?q?=E5=AD=97=E8=A1=A5=E5=85=A8=E5=8A=A0=E7=BE=A4=E6=88=90=E5=91=98?=
 =?UTF-8?q?/=E4=B8=BB=E5=8A=A8@=E5=85=9C=E5=BA=95=EF=BC=8C=E4=BF=AE=204105?=
 =?UTF-8?q?0=20=E6=AF=8F=E6=9D=A1=E7=99=BD=E6=89=93=20contact=20API?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

被别人 @ 时 <sender> 显示不出对方姓名：根因是 contact.v3.user.get 受飞书
「通讯录可见范围」限制，范围外用户返回 41050 no user authority。原代码只
特判 99991672(app 级缺 scope)，41050 落到 debug 静默吞掉且不缓存，导致每条
消息都白打一次 800ms 预算的 contact API。

改成 4 层解析，拿到即停：
1. 身份缓存（mention 学过的，免费）
2. contact API —— 41050 按 open_id 负缓存，不再每条重打（区别 99991672 的 app 级熔断）
3. 群成员 API —— 新增 listChatMembersWithNames，默认翻 1 页拿 (open_id,name)，
   顺便整群灌缓存；不需通讯录可见范围权限，失败降级空数组
4. 主动 @ 探针 —— 在消息所在群/话题 @ 对方发 /introduce，从自己发出消息的
   getMessageDetail 回执读飞书回填的 name，随即撤回

防护与防循环：
- 仅 sender_type==='user' 才探针，bot 走 bot-openids 跨引用名字、绝不被探
- 探针文本用 /introduce：万一误判 @ 到 bot，对方走现成 introduce 路由层
  short-circuit 不被唤起干活；防循环天然成立（探针 sender 是 bot，对方
  user-only gate 直接挡掉，不反向探测）
- 话题群在 thread 内发、普通群在群里发，绝不私聊（bot 无法私聊陌生人）

单测覆盖：41050 负缓存（per-user 非 per-app）、群成员翻页/降级、4 层降级
编排、enrichSenderName gate、探针撤回兜底。pnpm build / tsc / 全量套件全 exit 0。
---
 src/daemon.ts                             |  16 ++-
 src/im/lark/client.ts                     |  47 ++++++++
 src/im/lark/identity-cache.ts             |  16 ++-
 src/im/lark/sender-name-fallback.ts       | 123 ++++++++++++++++++++
 test/identity-cache.test.ts               |  67 +++++++++++
 test/list-chat-members-with-names.test.ts |  66 +++++++++++
 test/sender-name-fallback.test.ts         | 134 ++++++++++++++++++++++
 7 files changed, 466 insertions(+), 3 deletions(-)
 create mode 100644 src/im/lark/sender-name-fallback.ts
 create mode 100644 test/identity-cache.test.ts
 create mode 100644 test/list-chat-members-with-names.test.ts
 create mode 100644 test/sender-name-fallback.test.ts

diff --git a/src/daemon.ts b/src/daemon.ts
index 741e3837..b7d20058 100644
--- a/src/daemon.ts
+++ b/src/daemon.ts
@@ -92,6 +92,7 @@ import { EventLog as WorkflowEventLog } from './workflows/events/append.js';
 import { replay as replayWorkflow } from './workflows/events/replay.js';
 import { isBotMentioned, probeBotOpenId, startLarkEventDispatcher, writeBotInfoFile, canOperate, evaluateTalk, grantCommandRestriction, isKnownPeerBot, checkRequiredScopes, type RoutingContext, type TalkEvaluation } from './im/lark/event-dispatcher.js';
 import { learnFromMentions, resolveSender, flushIdentityCacheSync } from './im/lark/identity-cache.js';
+import { enrichSenderName } from './im/lark/sender-name-fallback.js';
 import { renderSenderTag } from './core/session-manager.js';
 import { markSessionActivity } from './core/session-activity.js';
 import { WorkflowEventWatcher, handleWorkflowFanoutEvent } from './workflows/fanout.js';
@@ -1973,7 +1974,14 @@ async function handleNewTopic(data: any, ctx: RoutingContext): Promise<void> {
   // Resolve sender identity for <sender> tag injection. The first call to
   // resolveSender for an unseen open_id may await contact.v3.user.get with a
   // short budget; subsequent calls hit the cache and are sync-fast.
-  const newTopicSender = await resolveSender(larkAppId, senderOpenId, parsed.senderType);
+  // enrichSenderName adds the chat-members + proactive-@ fallbacks (blocking)
+  // so a first-turn from an out-of-scope user still carries a name; it no-ops
+  // for bots and already-named senders.
+  const newTopicSender = await enrichSenderName(
+    larkAppId,
+    await resolveSender(larkAppId, senderOpenId, parsed.senderType),
+    { chatId, scope, anchor },
+  );
 
   refreshCliVersion(botCfg.cliId, botCfg.cliPathOverride);
 
@@ -2358,12 +2366,16 @@ async function handleThreadReply(data: any, ctx: RoutingContext): Promise<void>
   const getThreadSender = async (): Promise<typeof threadSenderCached> => {
     if (threadSenderResolved) return threadSenderCached;
     threadSenderResolved = true;
-    threadSenderCached = await resolveSender(
+    const resolved = await resolveSender(
       larkAppId,
       senderOpenIdForPrefix,
       parsed.senderType,
       isForeignBot ? { type: 'bot', name: foreignBotName !== 'Bot' ? foreignBotName : undefined } : undefined,
     );
+    const probeChatId = ctxChatId ?? data?.message?.chat_id;
+    threadSenderCached = probeChatId
+      ? await enrichSenderName(larkAppId, resolved, { chatId: probeChatId, scope, anchor })
+      : resolved;
     return threadSenderCached;
   };
 
diff --git a/src/im/lark/client.ts b/src/im/lark/client.ts
index 4a678bd9..430e7d48 100644
--- a/src/im/lark/client.ts
+++ b/src/im/lark/client.ts
@@ -300,6 +300,53 @@ export async function listChatMemberOpenIds(larkAppId: string, chatId: string):
   return openIds;
 }
 
+/**
+ * List chat members as (open_id, name) pairs — the name source that does NOT
+ * require 通讯录可见范围 (contact:user.base:readonly). Used as a sender-name
+ * fallback when contact.v3.user.get returns 41050 for an out-of-scope user:
+ * the sender is by definition a member of the chat it just posted in, so a
+ * single members page usually resolves it.
+ *
+ * Best-effort by design (UNLIKE `listChatMemberOpenIds`, which throws): a
+ * failure here just means "couldn't learn the name this way", and the caller
+ * falls through to the next resolution layer. So we swallow errors → [].
+ *
+ * `maxPages` defaults to 1: members pages are 100 max and pagination is serial
+ * (~0.4s/page), so walking a 5000-member group would blow the sender-resolve
+ * budget. One page covers typical topic/project groups; larger groups fall
+ * through to the proactive-@ probe.
+ */
+export async function listChatMembersWithNames(
+  larkAppId: string,
+  chatId: string,
+  maxPages = 1,
+): Promise<Array<{ openId: string; name: string }>> {
+  try {
+    const c = getBotClient(larkAppId);
+    const out: Array<{ openId: string; name: string }> = [];
+    let pageToken: string | undefined;
+    for (let page = 0; page < maxPages; page++) {
+      const params: Record<string, string> = { member_id_type: 'open_id', page_size: '100' };
+      if (pageToken) params.page_token = pageToken;
+      const res = await larkGet(c, `/open-apis/im/v1/chats/${encodeURIComponent(chatId)}/members`, params);
+      if (res.code !== 0) break;
+      for (const it of (res.data?.items ?? [])) {
+        const openId = it?.member_id;
+        const name = it?.name;
+        if (typeof openId === 'string' && openId && typeof name === 'string' && name) {
+          out.push({ openId, name });
+        }
+      }
+      if (!res.data?.has_more || !res.data?.page_token) break;
+      pageToken = res.data.page_token;
+    }
+    return out;
+  } catch (err) {
+    logger.debug(`listChatMembersWithNames(${chatId}) failed: ${err}`);
+    return [];
+  }
+}
+
 /**
  * Resolve a chat's display name (the user-facing group title). Returns `null`
  * on any failure (chatId is unknown to this bot, network error, bot not in
diff --git a/src/im/lark/identity-cache.ts b/src/im/lark/identity-cache.ts
index 752b8c1c..b5d526a5 100644
--- a/src/im/lark/identity-cache.ts
+++ b/src/im/lark/identity-cache.ts
@@ -31,13 +31,19 @@ export interface IdentityRecord {
   openId: string;
   type: IdentityType;
   name?: string;
-  source: 'sender' | 'mention' | 'contact_api' | 'bot_cross_ref' | 'bot_info';
+  source: 'sender' | 'mention' | 'contact_api' | 'bot_cross_ref' | 'bot_info' | 'chat_member' | 'introduce_probe';
   updatedAt: number;
 }
 
 const stores = new Map<string, Map<string, IdentityRecord>>();
 const inflight = new Map<string, Promise<void>>();
 const scopeUnavailable = new Set<string>();
+// Per-`${larkAppId}:${openId}` negative cache for contact.v3.user.get code
+// 41050 "no user authority error" — that specific user sits outside the app's
+// 通讯录可见范围. Unlike 99991672 (whole-app scope missing → app-wide breaker),
+// 41050 is per-user, so we mark just that open_id. Without this, every inbound
+// message from an out-of-scope user re-burns the 800ms-budgeted contact call.
+const unresolvableUsers = new Set<string>();
 const dirty = new Set<string>();
 let flushTimer: NodeJS.Timeout | null = null;
 
@@ -175,6 +181,7 @@ export async function resolveName(larkAppId: string, openId: string): Promise<st
   if (cached?.name) return cached.name;
   if (cached?.type === 'bot' || cached?.type === 'app') return undefined;
   if (scopeUnavailable.has(larkAppId)) return undefined;
+  if (unresolvableUsers.has(`${larkAppId}:${openId}`)) return undefined;
 
   const key = `${larkAppId}:${openId}`;
   let pending = inflight.get(key);
@@ -235,6 +242,13 @@ async function fetchUserName(larkAppId: string, openId: string): Promise<void> {
       }
       return;
     }
+    // 41050 = no user authority：该 user 不在 app 通讯录可见范围。per-user 负缓存
+    // （区别于 99991672 的 app 级熔断），避免每条消息重打 contact API。后续的群成员
+    // API / 主动 @ 兜底层仍可拿到这个人的名字，所以这里降级不影响最终解析结果。
+    if (res?.code === 41050) {
+      unresolvableUsers.add(`${larkAppId}:${openId}`);
+      return;
+    }
     logger.debug(
       `[identity] contact.user.get(${openId.substring(0, 12)}) code=${res?.code} msg=${res?.msg ?? ''}`,
     );
diff --git a/src/im/lark/sender-name-fallback.ts b/src/im/lark/sender-name-fallback.ts
new file mode 100644
index 00000000..f7a9fe6d
--- /dev/null
+++ b/src/im/lark/sender-name-fallback.ts
@@ -0,0 +1,123 @@
+/**
+ * Sender-name resolution, layers 3 & 4 — the fallbacks beyond identity-cache's
+ * cache (layer 1) and contact.v3.user.get (layer 2). Invoked by the daemon
+ * ONLY when layers 1-2 missed AND the sender is a real user (the daemon gates
+ * `sender_type === 'user'` so we never probe a bot — see the call site).
+ *
+ *   Layer 3 — chat members: list ONE page of the chat's members (name source
+ *     that needs no 通讯录可见范围). The sender is by definition a member of the
+ *     chat it just posted in, so this resolves typical (≤100-member) groups and
+ *     seeds the whole page into the cache for free.
+ *   Layer 4 — proactive @ probe: when layer 3 misses (big group / not on page
+ *     1), @-mention the sender in-place (NEVER a private DM — bots can't DM
+ *     strangers), read the name Lark backfills into the sent message, then
+ *     recall it. The probe text is `/introduce` so that if the gate ever
+ *     misfires onto a bot, the receiver short-circuits via its existing
+ *     /introduce handler instead of spawning a CLI turn.
+ *
+ * Returns the resolved name or undefined; degrades silently (no throws) so the
+ * caller can fall through to rendering the open_id.
+ */
+import { logger } from '../../utils/logger.js';
+import { recordIdentity } from './identity-cache.js';
+import type { ResolvedSender } from './identity-cache.js';
+import {
+  listChatMembersWithNames,
+  sendMessage,
+  replyMessage,
+  getMessageDetail,
+  deleteMessage,
+} from './client.js';
+
+export interface SenderNameCtx {
+  chatId: string;
+  scope: 'thread' | 'chat';
+  /** Thread root message_id (thread-scope) — used so the probe replies inside
+   *  the thread rather than spawning a new topic. */
+  anchor?: string;
+  /** Probe text; MUST keep `/introduce` at command position so a misfired bot
+   *  short-circuits. Defaults to `/introduce`. */
+  probeText?: string;
+}
+
+/**
+ * Daemon-facing gate + merge: run the fallback layers ONLY for a nameless real
+ * user, then fold the resolved name back into the sender. Keeps the gate
+ * (`type === 'user'`, no existing name, has chatId) in one tested place so the
+ * daemon call sites stay one-liners. A bot sender is returned untouched — this
+ * is what structurally prevents the probe from ever @-ing (and looping with)
+ * another bot.
+ */
+export async function enrichSenderName(
+  larkAppId: string,
+  sender: ResolvedSender | undefined,
+  ctx: SenderNameCtx,
+): Promise<ResolvedSender | undefined> {
+  if (!sender) return sender;
+  if (sender.name) return sender;
+  if (sender.type !== 'user') return sender;
+  if (!ctx?.chatId) return sender;
+  const name = await resolveSenderNameFallback(larkAppId, sender.openId, ctx);
+  return name ? { ...sender, name } : sender;
+}
+
+export async function resolveSenderNameFallback(
+  larkAppId: string,
+  openId: string,
+  ctx: SenderNameCtx,
+): Promise<string | undefined> {
+  if (!openId || !ctx?.chatId) return undefined;
+
+  // ── Layer 3: chat members (one page) ──────────────────────────────────────
+  const members = await listChatMembersWithNames(larkAppId, ctx.chatId, 1);
+  for (const member of members) {
+    recordIdentity(larkAppId, { openId: member.openId, name: member.name, type: 'user', source: 'chat_member' });
+  }
+  const fromMembers = members.find((member) => member.openId === openId)?.name;
+  if (fromMembers) return fromMembers;
+
+  // ── Layer 4: proactive @ probe + recall ───────────────────────────────────
+  return probeNameViaMention(larkAppId, openId, ctx);
+}
+
+async function probeNameViaMention(
+  larkAppId: string,
+  openId: string,
+  ctx: SenderNameCtx,
+): Promise<string | undefined> {
+  // `<at user_id=...>` is the inline @ form Lark backfills with the display
+  // name on send; after the receiver strips the leading @ the text is
+  // `/introduce`, matching its INTRODUCE_RE short-circuit.
+  const text = `<at user_id="${openId}"></at> ${ctx.probeText ?? '/introduce'}`;
+
+  let messageId: string | undefined;
+  try {
+    messageId =
+      ctx.scope === 'thread' && ctx.anchor
+        ? await replyMessage(larkAppId, ctx.anchor, text, 'text', true)
+        : await sendMessage(larkAppId, ctx.chatId, text, 'text');
+  } catch (err) {
+    logger.debug(`[identity] name probe send failed for ${openId.substring(0, 12)}: ${err}`);
+    return undefined;
+  }
+
+  let name: string | undefined;
+  try {
+    // userCardContent:false → plain GET (no card_msg_content_type param),
+    // matching the verified path for a text message; mentions[].name is what we read.
+    const detail = await getMessageDetail(larkAppId, messageId, { userCardContent: false });
+    const msg = Array.isArray(detail?.items) ? detail.items[0] : detail;
+    const mention = (msg?.mentions ?? []).find((mt: any) => mt?.id === openId);
+    if (typeof mention?.name === 'string' && mention.name) {
+      name = mention.name;
+      recordIdentity(larkAppId, { openId, name, type: 'user', source: 'introduce_probe' });
+    }
+  } catch (err) {
+    logger.debug(`[identity] name probe read failed for ${openId.substring(0, 12)}: ${err}`);
+  } finally {
+    // Always recall — an un-recalled probe is exactly the visible noise we're
+    // trying to avoid. Best-effort: a failed recall just leaves a stray line.
+    await deleteMessage(larkAppId, messageId).catch(() => {});
+  }
+  return name;
+}
diff --git a/test/identity-cache.test.ts b/test/identity-cache.test.ts
new file mode 100644
index 00000000..40311688
--- /dev/null
+++ b/test/identity-cache.test.ts
@@ -0,0 +1,67 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const state = vi.hoisted(() => ({ dataDir: '', larkGet: null as any }));
+
+vi.mock('../src/config.js', () => ({
+  config: { session: { get dataDir() { return state.dataDir; } } },
+}));
+vi.mock('../src/utils/logger.js', () => ({
+  logger: { info: vi.fn(), debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+vi.mock('../src/bot-registry.js', () => ({
+  getBotClient: vi.fn(() => ({ __mock: true })),
+}));
+vi.mock('../src/im/lark/client.js', () => ({
+  larkGet: (...args: any[]) => state.larkGet(...args),
+}));
+
+let seq = 0;
+/** Unique larkAppId per test so module-level caches don't bleed across cases. */
+function freshApp(): string {
+  return `cli_test_${Date.now()}_${seq++}`;
+}
+
+describe('identity-cache resolveName — 41050 negative cache', () => {
+  beforeEach(() => {
+    state.dataDir = mkdtempSync(join(tmpdir(), 'botmux-identity-'));
+  });
+  afterEach(async () => {
+    const { flushIdentityCacheSync } = await import('../src/im/lark/identity-cache.js');
+    flushIdentityCacheSync();
+    if (state.dataDir) {
+      rmSync(state.dataDir, { recursive: true, force: true });
+      state.dataDir = '';
+    }
+  });
+
+  it('does not re-call contact API after a 41050 no-authority response', async () => {
+    state.larkGet = vi.fn(async () => ({ code: 41050, msg: 'no user authority error' }));
+    const { resolveName } = await import('../src/im/lark/identity-cache.js');
+    const app = freshApp();
+
+    const n1 = await resolveName(app, 'ou_unknown_user');
+    const n2 = await resolveName(app, 'ou_unknown_user');
+
+    expect(n1).toBeUndefined();
+    expect(n2).toBeUndefined();
+    // The 41050 result is negative-cached per open_id → the second lookup must
+    // NOT hit the contact API again (otherwise every inbound message re-burns it).
+    expect(state.larkGet).toHaveBeenCalledTimes(1);
+  });
+
+  it('keeps re-trying a different open_id (negative cache is per-user, not per-app)', async () => {
+    state.larkGet = vi.fn(async () => ({ code: 41050, msg: 'no user authority error' }));
+    const { resolveName } = await import('../src/im/lark/identity-cache.js');
+    const app = freshApp();
+
+    await resolveName(app, 'ou_user_a');
+    await resolveName(app, 'ou_user_b');
+
+    // 41050 is "this user not visible", not "scope missing app-wide" — so a
+    // brand-new open_id still gets one attempt.
+    expect(state.larkGet).toHaveBeenCalledTimes(2);
+  });
+});
diff --git a/test/list-chat-members-with-names.test.ts b/test/list-chat-members-with-names.test.ts
new file mode 100644
index 00000000..5d6e8e05
--- /dev/null
+++ b/test/list-chat-members-with-names.test.ts
@@ -0,0 +1,66 @@
+import { describe, expect, it, vi } from 'vitest';
+
+const state = vi.hoisted(() => ({ pages: [] as any[], calls: [] as any[] }));
+
+vi.mock('../src/config.js', () => ({
+  config: { session: { dataDir: '/tmp/botmux-test' } },
+}));
+vi.mock('../src/utils/logger.js', () => ({
+  logger: { info: vi.fn(), debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+vi.mock('../src/bot-registry.js', () => ({
+  getBotClient: vi.fn(() => ({
+    request: async (req: any) => {
+      state.calls.push(req);
+      return state.pages.shift() ?? { code: 0, data: { items: [], has_more: false } };
+    },
+  })),
+  loadBotConfigs: vi.fn(() => []),
+}));
+
+describe('listChatMembersWithNames', () => {
+  it('returns (openId, name) pairs for chat members', async () => {
+    state.pages = [{ code: 0, data: { items: [
+      { member_id: 'ou_a', name: '张三' },
+      { member_id: 'ou_b', name: '李四' },
+    ], has_more: false } }];
+    state.calls = [];
+    const { listChatMembersWithNames } = await import('../src/im/lark/client.js');
+    const members = await listChatMembersWithNames('cli_x', 'oc_chat');
+    expect(members).toEqual([
+      { openId: 'ou_a', name: '张三' },
+      { openId: 'ou_b', name: '李四' },
+    ]);
+  });
+
+  it('defaults to a single page even when more pages exist', async () => {
+    state.pages = [
+      { code: 0, data: { items: [{ member_id: 'ou_a', name: '张三' }], has_more: true, page_token: 'p2' } },
+      { code: 0, data: { items: [{ member_id: 'ou_b', name: '李四' }], has_more: false } },
+    ];
+    state.calls = [];
+    const { listChatMembersWithNames } = await import('../src/im/lark/client.js');
+    const members = await listChatMembersWithNames('cli_x', 'oc_chat');
+    expect(members).toEqual([{ openId: 'ou_a', name: '张三' }]); // only page 1
+    expect(state.calls).toHaveLength(1); // did not fetch page 2
+  });
+
+  it('skips items missing a name (e.g. bot members), keeps named users', async () => {
+    state.pages = [{ code: 0, data: { items: [
+      { member_id: 'ou_named', name: '王五' },
+      { member_id: 'ou_noname', name: '' },
+      { member_id: '', name: '空' },
+    ], has_more: false } }];
+    state.calls = [];
+    const { listChatMembersWithNames } = await import('../src/im/lark/client.js');
+    const members = await listChatMembersWithNames('cli_x', 'oc_chat');
+    expect(members).toEqual([{ openId: 'ou_named', name: '王五' }]);
+  });
+
+  it('degrades to [] on API error instead of throwing', async () => {
+    state.pages = [{ code: 99991663, msg: 'permission denied' }];
+    state.calls = [];
+    const { listChatMembersWithNames } = await import('../src/im/lark/client.js');
+    await expect(listChatMembersWithNames('cli_x', 'oc_chat')).resolves.toEqual([]);
+  });
+});
diff --git a/test/sender-name-fallback.test.ts b/test/sender-name-fallback.test.ts
new file mode 100644
index 00000000..26f9f63e
--- /dev/null
+++ b/test/sender-name-fallback.test.ts
@@ -0,0 +1,134 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const m = vi.hoisted(() => ({
+  listMembers: vi.fn(),
+  send: vi.fn(),
+  reply: vi.fn(),
+  getDetail: vi.fn(),
+  del: vi.fn(),
+  record: vi.fn(),
+}));
+
+vi.mock('../src/utils/logger.js', () => ({
+  logger: { info: vi.fn(), debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+vi.mock('../src/im/lark/client.js', () => ({
+  listChatMembersWithNames: (...a: any[]) => m.listMembers(...a),
+  sendMessage: (...a: any[]) => m.send(...a),
+  replyMessage: (...a: any[]) => m.reply(...a),
+  getMessageDetail: (...a: any[]) => m.getDetail(...a),
+  deleteMessage: (...a: any[]) => m.del(...a),
+}));
+vi.mock('../src/im/lark/identity-cache.js', () => ({
+  recordIdentity: (...a: any[]) => m.record(...a),
+}));
+
+beforeEach(() => {
+  Object.values(m).forEach((fn) => fn.mockReset());
+  m.del.mockResolvedValue(true);
+});
+
+describe('resolveSenderNameFallback', () => {
+  it('layer 3: resolves from chat members without probing', async () => {
+    m.listMembers.mockResolvedValue([
+      { openId: 'ou_other', name: '他人' },
+      { openId: 'ou_target', name: '目标用户' },
+    ]);
+    const { resolveSenderNameFallback } = await import('../src/im/lark/sender-name-fallback.js');
+    const name = await resolveSenderNameFallback('cli_x', 'ou_target', { chatId: 'oc_c', scope: 'chat' });
+    expect(name).toBe('目标用户');
+    expect(m.send).not.toHaveBeenCalled();
+    expect(m.reply).not.toHaveBeenCalled();
+    // seeds the whole members page into the cache (free coverage for everyone)
+    expect(m.record).toHaveBeenCalledTimes(2);
+  });
+
+  it('layer 4: probes via @mention + recall when members miss (chat scope)', async () => {
+    m.listMembers.mockResolvedValue([{ openId: 'ou_other', name: '他人' }]);
+    m.send.mockResolvedValue('om_probe');
+    m.getDetail.mockResolvedValue({ items: [{ mentions: [{ id: 'ou_target', name: '探针名' }] }] });
+    const { resolveSenderNameFallback } = await import('../src/im/lark/sender-name-fallback.js');
+    const name = await resolveSenderNameFallback('cli_x', 'ou_target', { chatId: 'oc_c', scope: 'chat' });
+    expect(name).toBe('探针名');
+    // probe @s the target AND carries /introduce so a misfired bot short-circuits
+    const [, , content, msgType] = m.send.mock.calls[0];
+    expect(content).toContain('ou_target');
+    expect(content).toContain('/introduce');
+    expect(msgType).toBe('text');
+    expect(m.del).toHaveBeenCalledWith('cli_x', 'om_probe');
+    expect(m.record).toHaveBeenCalledWith('cli_x', expect.objectContaining({ openId: 'ou_target', name: '探针名' }));
+  });
+
+  it('layer 4: thread scope replies in-thread using the anchor', async () => {
+    m.listMembers.mockResolvedValue([]);
+    m.reply.mockResolvedValue('om_probe');
+    m.getDetail.mockResolvedValue({ items: [{ mentions: [{ id: 'ou_target', name: '楼主' }] }] });
+    const { resolveSenderNameFallback } = await import('../src/im/lark/sender-name-fallback.js');
+    const name = await resolveSenderNameFallback('cli_x', 'ou_target', { chatId: 'oc_c', scope: 'thread', anchor: 'om_root' });
+    expect(name).toBe('楼主');
+    const [, msgId, , , replyInThread] = m.reply.mock.calls[0];
+    expect(msgId).toBe('om_root');
+    expect(replyInThread).toBe(true);
+    expect(m.send).not.toHaveBeenCalled();
+    expect(m.del).toHaveBeenCalledWith('cli_x', 'om_probe');
+  });
+
+  it('recalls the probe even when no name was backfilled', async () => {
+    m.listMembers.mockResolvedValue([]);
+    m.send.mockResolvedValue('om_probe');
+    m.getDetail.mockResolvedValue({ items: [{ mentions: [] }] });
+    const { resolveSenderNameFallback } = await import('../src/im/lark/sender-name-fallback.js');
+    const name = await resolveSenderNameFallback('cli_x', 'ou_target', { chatId: 'oc_c', scope: 'chat' });
+    expect(name).toBeUndefined();
+    expect(m.del).toHaveBeenCalledWith('cli_x', 'om_probe');
+  });
+
+  it('returns undefined (no throw) when the probe send itself fails', async () => {
+    m.listMembers.mockResolvedValue([]);
+    m.send.mockRejectedValue(new Error('send boom'));
+    const { resolveSenderNameFallback } = await import('../src/im/lark/sender-name-fallback.js');
+    await expect(
+      resolveSenderNameFallback('cli_x', 'ou_target', { chatId: 'oc_c', scope: 'chat' }),
+    ).resolves.toBeUndefined();
+    expect(m.del).not.toHaveBeenCalled(); // no message_id to recall
+  });
+});
+
+describe('enrichSenderName (gate)', () => {
+  it('never probes a bot sender', async () => {
+    const { enrichSenderName } = await import('../src/im/lark/sender-name-fallback.js');
+    const out = await enrichSenderName('cli_x', { openId: 'ou_bot', type: 'bot' }, { chatId: 'oc_c', scope: 'chat' });
+    expect(out).toEqual({ openId: 'ou_bot', type: 'bot' });
+    expect(m.listMembers).not.toHaveBeenCalled();
+    expect(m.send).not.toHaveBeenCalled();
+  });
+
+  it('does not probe when the name is already resolved (layers 1-2 hit)', async () => {
+    const { enrichSenderName } = await import('../src/im/lark/sender-name-fallback.js');
+    const out = await enrichSenderName('cli_x', { openId: 'ou_u', type: 'user', name: '已知' }, { chatId: 'oc_c', scope: 'chat' });
+    expect(out).toEqual({ openId: 'ou_u', type: 'user', name: '已知' });
+    expect(m.listMembers).not.toHaveBeenCalled();
+  });
+
+  it('probes a nameless user sender and merges the resolved name', async () => {
+    m.listMembers.mockResolvedValue([{ openId: 'ou_u', name: '查到的名' }]);
+    const { enrichSenderName } = await import('../src/im/lark/sender-name-fallback.js');
+    const out = await enrichSenderName('cli_x', { openId: 'ou_u', type: 'user' }, { chatId: 'oc_c', scope: 'chat' });
+    expect(out).toEqual({ openId: 'ou_u', type: 'user', name: '查到的名' });
+  });
+
+  it('returns the sender unchanged when the fallback finds nothing', async () => {
+    m.listMembers.mockResolvedValue([]);
+    m.send.mockResolvedValue('om_p');
+    m.getDetail.mockResolvedValue({ items: [{ mentions: [] }] });
+    const { enrichSenderName } = await import('../src/im/lark/sender-name-fallback.js');
+    const out = await enrichSenderName('cli_x', { openId: 'ou_u', type: 'user' }, { chatId: 'oc_c', scope: 'chat' });
+    expect(out).toEqual({ openId: 'ou_u', type: 'user' });
+  });
+
+  it('passes an undefined sender straight through', async () => {
+    const { enrichSenderName } = await import('../src/im/lark/sender-name-fallback.js');
+    expect(await enrichSenderName('cli_x', undefined, { chatId: 'oc_c', scope: 'chat' })).toBeUndefined();
+    expect(m.listMembers).not.toHaveBeenCalled();
+  });
+});

From 7ccbfd44e54be516fc1d8653adb3986a417985b9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=94=B3=E6=99=97?= <deepcoldy@gmail.com>
Date: Tue, 2 Jun 2026 03:28:02 +0800
Subject: [PATCH 7/7] =?UTF-8?q?fix(identity):=20=E6=8C=89=20Codex=20review?=
 =?UTF-8?q?=20=E4=BF=AE=E6=8E=A2=E9=92=88=E9=98=B2=E8=AF=AF=E8=A7=A6?=
 =?UTF-8?q?=E5=8F=91=E6=BC=8F=E6=B4=9E=20+=20=E5=8A=A0=20timeout/=E5=A4=B1?=
 =?UTF-8?q?=E8=B4=A5=E5=86=B7=E5=8D=B4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

回应 Codex 对 PR #87 的两个 P1 + 一个建议：

P1-1 防误触发漏洞（event-dispatcher）：bot-originated 消息先进 isBotSenderType
分支并 route 到 handleThreadReply，而 /introduce 的 short-circuit 在后面的
user 分支才跑——所以探针误判 @ 到 bot 时，对方可能把 /introduce 当 prompt
喂进 CLI。修法：在 bot 分支里、foreign-bot 路由之前，先静默 consume
bot-originated /introduce（tryHandleIntroduceCommand 加 silent 选项，不 ack、
不 route）。防*循环*本身仍靠双侧 user-only gate；这里修的是「别误唤起对方 CLI」。

P1-2 探针 timeout + 失败冷却（sender-name-fallback）：
- getMessageDetail 加读取 budget（默认 1.5s，可注入），超时也照样撤回——避免
  SDK 无超时时 get 挂住既留下可见探针又阻塞 inbound；
- 撤回改 fire-and-forget，不阻塞当前 inbound；
- 群成员 + 探针都没拿到名字时，按 open_id 加短 TTL（10min）负缓存，避免同一
  sender 每条消息都 send→get→delete 一轮刷屏。

建议项：41050 负缓存从进程内 Set 升级为 Map<key,expiresAt>，TTL 24h——可见
范围变化后隔天能重试一次 contact，而非同进程永不重试。

测试：event-dispatcher 75（+1 静默 consume）、sender-name-fallback 14
（+timeout/冷却）、identity-cache 3（+TTL 到期重试）；tsc 全量 exit 0。
---
 src/im/lark/event-dispatcher.ts     | 23 +++++++--
 src/im/lark/identity-cache.ts       | 20 +++++---
 src/im/lark/sender-name-fallback.ts | 76 ++++++++++++++++++++++-------
 test/event-dispatcher.test.ts       | 18 +++++++
 test/identity-cache.test.ts         | 24 +++++++++
 test/sender-name-fallback.test.ts   | 50 +++++++++++++++++++
 6 files changed, 182 insertions(+), 29 deletions(-)

diff --git a/src/im/lark/event-dispatcher.ts b/src/im/lark/event-dispatcher.ts
index 719cd866..2e743352 100644
--- a/src/im/lark/event-dispatcher.ts
+++ b/src/im/lark/event-dispatcher.ts
@@ -395,6 +395,7 @@ export async function tryHandleIntroduceCommand(
   larkAppId: string,
   message: any,
   senderOpenId: string | undefined,
+  opts: { silent?: boolean } = {},
 ): Promise<boolean> {
   const text = extractMessageTextForRouting(message);
   if (!text) return false;
@@ -405,10 +406,12 @@ export async function tryHandleIntroduceCommand(
   logger.debug(`[${larkAppId}] /introduce from ${senderOpenId ?? 'unknown'} (no auth required)`);
 
   if (grantCommandRestriction(larkAppId, message.chat_id, senderOpenId).blocked) {
-    const loc = localeForBot(larkAppId);
-    await replyMessage(larkAppId, message.message_id, JSON.stringify({
-      text: t('cmd.grant_restricted', { cmd: '/introduce' }, loc),
-    })).catch(err => logger.debug(`introduce grant_restricted reply failed: ${err}`));
+    if (!opts.silent) {
+      const loc = localeForBot(larkAppId);
+      await replyMessage(larkAppId, message.message_id, JSON.stringify({
+        text: t('cmd.grant_restricted', { cmd: '/introduce' }, loc),
+      })).catch(err => logger.debug(`introduce grant_restricted reply failed: ${err}`));
+    }
     return true;
   }
 
@@ -440,6 +443,9 @@ export async function tryHandleIntroduceCommand(
     logger.warn(`[${larkAppId}] /introduce: failed to persist observed bots: ${err}`);
   }
 
+  // Silent mode (bot-originated probe): record but never echo an ack.
+  if (opts.silent) return true;
+
   const externalBots = bots.filter(m => m.openId !== selfOpenId);
   const ackText = externalBots.length
     ? `✅ 已认识本群 ${externalBots.length} 个伙伴：${externalBots.map(m => `@${m.name}`).join(' ')}`
@@ -901,6 +907,15 @@ export function startLarkEventDispatcher(larkAppId: string, larkAppSecret: strin
               .catch(err => logger.error(`Error handling message event: ${err}`));
             return;
           }
+          // A bot-originated /introduce (e.g. a peer bot's name-resolution probe
+          // @ing us) must be consumed HERE — before foreign-bot routing — so it
+          // never spawns a CLI turn, and silently so it doesn't echo an ack.
+          // (Human-typed /introduce is a user-sender message, handled in the
+          // user branch below with its ack.) This is the receiver-side backstop
+          // for a sender-name probe that misfires onto a bot.
+          if (await tryHandleIntroduceCommand(larkAppId, message, senderOpenId, { silent: true })) {
+            return;
+          }
           // Foreign bot: only route on @mention of us.
           if (!isBotMentioned(larkAppId, message, undefined)) return;
           const ctx = await decideRouting(larkAppId, message);
diff --git a/src/im/lark/identity-cache.ts b/src/im/lark/identity-cache.ts
index b5d526a5..4d4cc344 100644
--- a/src/im/lark/identity-cache.ts
+++ b/src/im/lark/identity-cache.ts
@@ -38,17 +38,20 @@ export interface IdentityRecord {
 const stores = new Map<string, Map<string, IdentityRecord>>();
 const inflight = new Map<string, Promise<void>>();
 const scopeUnavailable = new Set<string>();
-// Per-`${larkAppId}:${openId}` negative cache for contact.v3.user.get code
-// 41050 "no user authority error" — that specific user sits outside the app's
-// 通讯录可见范围. Unlike 99991672 (whole-app scope missing → app-wide breaker),
-// 41050 is per-user, so we mark just that open_id. Without this, every inbound
-// message from an out-of-scope user re-burns the 800ms-budgeted contact call.
-const unresolvableUsers = new Set<string>();
+// Per-`${larkAppId}:${openId}` → expiry epoch ms. Negative cache for
+// contact.v3.user.get code 41050 "no user authority error" — that specific user
+// sits outside the app's 通讯录可见范围. Unlike 99991672 (whole-app scope missing
+// → app-wide breaker), 41050 is per-user, so we mark just that open_id. Without
+// this, every inbound message from an out-of-scope user re-burns the
+// 800ms-budgeted contact call. The TTL lets us retry once a day in case the
+// user's visibility scope changed (process-local; cleared on restart).
+const unresolvableUsers = new Map<string, number>();
 const dirty = new Set<string>();
 let flushTimer: NodeJS.Timeout | null = null;
 
 const FLUSH_DEBOUNCE_MS = 2_000;
 const RESOLVE_BUDGET_MS = 800;
+const NEG_CACHE_TTL_MS = 24 * 60 * 60 * 1_000;
 
 function cacheFile(larkAppId: string): string {
   return join(config.session.dataDir, `identities-${larkAppId}.json`);
@@ -181,7 +184,8 @@ export async function resolveName(larkAppId: string, openId: string): Promise<st
   if (cached?.name) return cached.name;
   if (cached?.type === 'bot' || cached?.type === 'app') return undefined;
   if (scopeUnavailable.has(larkAppId)) return undefined;
-  if (unresolvableUsers.has(`${larkAppId}:${openId}`)) return undefined;
+  const negExpiry = unresolvableUsers.get(`${larkAppId}:${openId}`);
+  if (negExpiry !== undefined && negExpiry > Date.now()) return undefined;
 
   const key = `${larkAppId}:${openId}`;
   let pending = inflight.get(key);
@@ -246,7 +250,7 @@ async function fetchUserName(larkAppId: string, openId: string): Promise<void> {
     // （区别于 99991672 的 app 级熔断），避免每条消息重打 contact API。后续的群成员
     // API / 主动 @ 兜底层仍可拿到这个人的名字，所以这里降级不影响最终解析结果。
     if (res?.code === 41050) {
-      unresolvableUsers.add(`${larkAppId}:${openId}`);
+      unresolvableUsers.set(`${larkAppId}:${openId}`, Date.now() + NEG_CACHE_TTL_MS);
       return;
     }
     logger.debug(
diff --git a/src/im/lark/sender-name-fallback.ts b/src/im/lark/sender-name-fallback.ts
index f7a9fe6d..44067cfd 100644
--- a/src/im/lark/sender-name-fallback.ts
+++ b/src/im/lark/sender-name-fallback.ts
@@ -38,6 +38,38 @@ export interface SenderNameCtx {
   /** Probe text; MUST keep `/introduce` at command position so a misfired bot
    *  short-circuits. Defaults to `/introduce`. */
   probeText?: string;
+  /** Read budget (ms) for the probe's getMessageDetail. Injectable for tests;
+   *  defaults to {@link PROBE_READ_BUDGET_MS}. */
+  readBudgetMs?: number;
+}
+
+/** Budget for reading back the probe message. The Lark SDK has no built-in
+ *  request timeout, so a hung read would both leave the probe visible AND block
+ *  the (synchronous) inbound handler — bound it and recall regardless. */
+const PROBE_READ_BUDGET_MS = 1500;
+
+/** How long a (members + probe) miss suppresses retries for one user. Without
+ *  it, every inbound message from an unresolvable sender (no chat-member name,
+ *  no @ backfill, missing message-read scope) re-runs send→get→recall. */
+const FALLBACK_NEG_TTL_MS = 10 * 60_000;
+
+/** `${larkAppId}:${openId}` → expiry epoch ms. Process-local; cleared on restart. */
+const fallbackCooldown = new Map<string, number>();
+
+/** Resolve `p` within `ms`, else resolve `fallback` (never rejects — a slow or
+ *  failing best-effort read should degrade, not throw). The underlying promise
+ *  is left to settle on its own. */
+function withTimeout<T>(p: Promise<T>, ms: number, fallback: T): Promise<T> {
+  return new Promise<T>((resolve) => {
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (!settled) { settled = true; resolve(fallback); }
+    }, ms);
+    p.then(
+      (v) => { if (!settled) { settled = true; clearTimeout(timer); resolve(v); } },
+      () => { if (!settled) { settled = true; clearTimeout(timer); resolve(fallback); } },
+    );
+  });
 }
 
 /**
@@ -68,6 +100,12 @@ export async function resolveSenderNameFallback(
 ): Promise<string | undefined> {
   if (!openId || !ctx?.chatId) return undefined;
 
+  // Recent (members + probe) miss for this user → skip the whole fallback so we
+  // don't re-burn an API + a visible @ probe on every message from them.
+  const cooldownKey = `${larkAppId}:${openId}`;
+  const until = fallbackCooldown.get(cooldownKey);
+  if (until !== undefined && until > Date.now()) return undefined;
+
   // ── Layer 3: chat members (one page) ──────────────────────────────────────
   const members = await listChatMembersWithNames(larkAppId, ctx.chatId, 1);
   for (const member of members) {
@@ -77,7 +115,9 @@ export async function resolveSenderNameFallback(
   if (fromMembers) return fromMembers;
 
   // ── Layer 4: proactive @ probe + recall ───────────────────────────────────
-  return probeNameViaMention(larkAppId, openId, ctx);
+  const probed = await probeNameViaMention(larkAppId, openId, ctx);
+  if (!probed) fallbackCooldown.set(cooldownKey, Date.now() + FALLBACK_NEG_TTL_MS);
+  return probed;
 }
 
 async function probeNameViaMention(
@@ -101,23 +141,25 @@ async function probeNameViaMention(
     return undefined;
   }
 
+  // Read back the message Lark backfilled with the display name. Bounded: a
+  // hung getMessageDetail must neither leave the probe visible nor block the
+  // inbound handler. userCardContent:false → plain GET (matching the verified
+  // text-message path).
+  const detail = await withTimeout(
+    getMessageDetail(larkAppId, messageId, { userCardContent: false }).catch(() => undefined),
+    ctx.readBudgetMs ?? PROBE_READ_BUDGET_MS,
+    undefined,
+  );
   let name: string | undefined;
-  try {
-    // userCardContent:false → plain GET (no card_msg_content_type param),
-    // matching the verified path for a text message; mentions[].name is what we read.
-    const detail = await getMessageDetail(larkAppId, messageId, { userCardContent: false });
-    const msg = Array.isArray(detail?.items) ? detail.items[0] : detail;
-    const mention = (msg?.mentions ?? []).find((mt: any) => mt?.id === openId);
-    if (typeof mention?.name === 'string' && mention.name) {
-      name = mention.name;
-      recordIdentity(larkAppId, { openId, name, type: 'user', source: 'introduce_probe' });
-    }
-  } catch (err) {
-    logger.debug(`[identity] name probe read failed for ${openId.substring(0, 12)}: ${err}`);
-  } finally {
-    // Always recall — an un-recalled probe is exactly the visible noise we're
-    // trying to avoid. Best-effort: a failed recall just leaves a stray line.
-    await deleteMessage(larkAppId, messageId).catch(() => {});
+  const msg = Array.isArray(detail?.items) ? detail.items[0] : detail;
+  const mention = (msg?.mentions ?? []).find((mt: any) => mt?.id === openId);
+  if (typeof mention?.name === 'string' && mention.name) {
+    name = mention.name;
+    recordIdentity(larkAppId, { openId, name, type: 'user', source: 'introduce_probe' });
   }
+
+  // Fire-and-forget recall — an un-recalled probe is the visible noise we're
+  // avoiding, but we must not block the inbound handler on recall latency.
+  void deleteMessage(larkAppId, messageId).catch(() => {});
   return name;
 }
diff --git a/test/event-dispatcher.test.ts b/test/event-dispatcher.test.ts
index e170b42b..e6fe0102 100644
--- a/test/event-dispatcher.test.ts
+++ b/test/event-dispatcher.test.ts
@@ -282,6 +282,24 @@ describe('im.message.receive_v1 — bot-to-bot @mention routing', () => {
     expect(handlers.handleThreadReply).not.toHaveBeenCalled();
   });
 
+  it('silently consumes a bot-originated /introduce probe (no route, no ack)', async () => {
+    // Another bot's name-resolution probe @s us with `/introduce`. It must be
+    // short-circuited BEFORE foreign-bot routing so it never spawns a CLI turn,
+    // and silently (no ack) so it doesn't echo noise back into the chat.
+    const event = makeBotMessageEvent({
+      senderOpenId: OTHER_BOT_OPEN_ID,
+      content: JSON.stringify({ text: '@_user_1 /introduce' }),
+      rootId: 'root-probe',
+      mentions: [{ key: '@_user_1', name: 'BotA', id: { open_id: MY_OPEN_ID } }],
+    });
+
+    await capturedHandlers['im.message.receive_v1'](event);
+
+    expect(handlers.handleThreadReply).not.toHaveBeenCalled();
+    expect(handlers.handleNewTopic).not.toHaveBeenCalled();
+    expect(mockReplyMessage).not.toHaveBeenCalled(); // silent — no /introduce ack
+  });
+
   it('routes @mentioned bot message to handleThreadReply', async () => {
     // Another bot sends a post message that @mentions this bot in a thread
     const postContent = JSON.stringify({
diff --git a/test/identity-cache.test.ts b/test/identity-cache.test.ts
index 40311688..8d7a6675 100644
--- a/test/identity-cache.test.ts
+++ b/test/identity-cache.test.ts
@@ -64,4 +64,28 @@ describe('identity-cache resolveName — 41050 negative cache', () => {
     // brand-new open_id still gets one attempt.
     expect(state.larkGet).toHaveBeenCalledTimes(2);
   });
+
+  it('retries the contact API only after the 41050 negative cache TTL expires', async () => {
+    vi.useFakeTimers();
+    try {
+      state.larkGet = vi.fn(async () => ({ code: 41050, msg: 'no user authority error' }));
+      const { resolveName } = await import('../src/im/lark/identity-cache.js');
+      const app = freshApp();
+
+      await resolveName(app, 'ou_u');
+      expect(state.larkGet).toHaveBeenCalledTimes(1);
+
+      // Within TTL: still suppressed.
+      await vi.advanceTimersByTimeAsync(60_000);
+      await resolveName(app, 'ou_u');
+      expect(state.larkGet).toHaveBeenCalledTimes(1);
+
+      // Past TTL (>24h): scope may have changed, so retry once more.
+      await vi.advanceTimersByTimeAsync(25 * 60 * 60 * 1000);
+      await resolveName(app, 'ou_u');
+      expect(state.larkGet).toHaveBeenCalledTimes(2);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
 });
diff --git a/test/sender-name-fallback.test.ts b/test/sender-name-fallback.test.ts
index 26f9f63e..80b3dc95 100644
--- a/test/sender-name-fallback.test.ts
+++ b/test/sender-name-fallback.test.ts
@@ -24,6 +24,9 @@ vi.mock('../src/im/lark/identity-cache.js', () => ({
 }));
 
 beforeEach(() => {
+  // Fresh module each test → the module-level negative cache doesn't bleed across cases.
+  vi.resetModules();
+  vi.useRealTimers();
   Object.values(m).forEach((fn) => fn.mockReset());
   m.del.mockResolvedValue(true);
 });
@@ -132,3 +135,50 @@ describe('enrichSenderName (gate)', () => {
     expect(m.listMembers).not.toHaveBeenCalled();
   });
 });
+
+describe('resolveSenderNameFallback — robustness (timeout + failure cooldown)', () => {
+  // readBudgetMs is injectable so these run in real time without fake timers.
+  it('recalls and returns undefined when the read exceeds the budget', async () => {
+    m.listMembers.mockResolvedValue([]);
+    m.send.mockResolvedValue('om_probe');
+    m.getDetail.mockReturnValue(new Promise(() => {})); // read hangs forever
+    const { resolveSenderNameFallback } = await import('../src/im/lark/sender-name-fallback.js');
+    const name = await resolveSenderNameFallback('cli_x', 'ou_t', { chatId: 'oc_c', scope: 'chat', readBudgetMs: 20 });
+    expect(name).toBeUndefined();
+    // a hung read must NOT leave the probe visible — recall fires regardless
+    expect(m.del).toHaveBeenCalledWith('cli_x', 'om_probe');
+  }, 2000);
+
+  it('does not block the result on a slow recall (fire-and-forget)', async () => {
+    m.listMembers.mockResolvedValue([]);
+    m.send.mockResolvedValue('om_probe');
+    m.getDetail.mockResolvedValue({ items: [{ mentions: [{ id: 'ou_t', name: '探到' }] }] });
+    m.del.mockReturnValue(new Promise(() => {})); // recall hangs
+    const { resolveSenderNameFallback } = await import('../src/im/lark/sender-name-fallback.js');
+    const name = await resolveSenderNameFallback('cli_x', 'ou_t', { chatId: 'oc_c', scope: 'chat' });
+    expect(name).toBe('探到');
+  }, 2000);
+
+  it('does not re-probe the same user after a failed probe (per-user negative cache)', async () => {
+    m.listMembers.mockResolvedValue([]);
+    m.send.mockResolvedValue('om_probe');
+    m.getDetail.mockResolvedValue({ items: [{ mentions: [] }] }); // no name backfilled
+    const { resolveSenderNameFallback } = await import('../src/im/lark/sender-name-fallback.js');
+    await resolveSenderNameFallback('cli_x', 'ou_t', { chatId: 'oc_c', scope: 'chat' });
+    await resolveSenderNameFallback('cli_x', 'ou_t', { chatId: 'oc_c', scope: 'chat' });
+    // 2nd inbound from the same unresolvable user must NOT send another probe…
+    expect(m.send).toHaveBeenCalledTimes(1);
+    // …nor re-hit the members API (the cooldown gates the whole fallback)
+    expect(m.listMembers).toHaveBeenCalledTimes(1);
+  });
+
+  it('cooldown is per-user — a different user is still probed', async () => {
+    m.listMembers.mockResolvedValue([]);
+    m.send.mockResolvedValue('om_probe');
+    m.getDetail.mockResolvedValue({ items: [{ mentions: [] }] });
+    const { resolveSenderNameFallback } = await import('../src/im/lark/sender-name-fallback.js');
+    await resolveSenderNameFallback('cli_x', 'ou_a', { chatId: 'oc_c', scope: 'chat' });
+    await resolveSenderNameFallback('cli_x', 'ou_b', { chatId: 'oc_c', scope: 'chat' });
+    expect(m.send).toHaveBeenCalledTimes(2);
+  });
+});