feat(session,runtime): 多角色并存—按会话选角（迁移0011 + 按回合解析 + agent池 + 提取器修正）

按 DevDocs/design/22 批次 1 后端（§2/§3/§4.1-4.5/§4.7/§5 验收 1-6）。
- 迁移 0011：chat_sessions.persona_id + chat_messages.persona_id（均 DEFAULT ''，无回填 → 升级零风险）；同步包内幂等 DDL；**真实库升级验证**（拷贝 data/cyrene.db 到临时目录跑 MigrateUp：既有 1 会话/109 消息 persona 仍为 ''，原库未被触碰）
- history：SessionMeta/Message 加 PersonaID + SetSessionPersona；ListSessions/List/scan/Append 带上
- runtime：SessionEnv.PersonaID + loop.personaFor(ctx) 替换固定 l.personaID（memory/request/turn）+ **agent 池**（Options.Agents，按角色取 instructions，未命中回落）+ **提取器不再把 persona 烤死在构造期**（多角色下记忆不再永远记在 cyrene 名下）+ **thinking 旋钮改为按会话角色解析**（否则角色 Y 会用角色 X 的预算/展示）
- gateway：会话 DTO/POST/PATCH 支持 personaId；ws/rest/voice 的 OwnerEnv 硬编改为**按会话解析角色**（actor 元数据语义不变）；admin memories 搜索去掉硬编 cyrene
- Docs/api-client v0.42；**两处有意的行为收紧**已写明：POST /sessions body 非法 JSON → 400（原先完全忽略 body；空/null/{} 仍 201）；POST /admin/memories/search 省略 personaId 且无默认角色 → 400（原先默认查 cyrene）
- 测试：design/22 §5 验收 1-6（记忆隔离/提示词首条 system/情绪按角色/提取 persona 归属/迁移兼容）+ 进程内 e2e（断言 adapter 收到的 model.Request.Messages[0] 即该角色的 systemPrompt）
- **已知未做（留批次 2 / 待确认）**：① IM 与渠道级未做 → **§7-3「owner 私聊镜像随主会话角色」尚未生效**；② 请求级覆盖未实现（本批只做会话级）；③ **§7-5 的「上下文发送角色标记」只完成存储+DTO 半边**——消息 persona 已落库且 DTO 已带，但模型上下文不从 chat_messages 重建，「第 N 条是谁说的」尚未进上下文（需确认是否属批次 2）；④「切角色重建摘要」当前是空操作（压缩未接线）；⑤ thinking 旋钮仅在流式路径生效（非流式 agent.RunStep 不带，A 批次既有性质）
- 验收：go build/vet/test 全绿 + linux/amd64 与 darwin/arm64 交叉编译（既有 flake 本轮未触发；同批 session_orchestrator.go 一度 501 行 → 抽出 session_tail.go）

Docs/api-client.md

@@ -26,13 +26,13 @@
 | 1b | `/api/v1/auth/logout` | POST | refreshToken 或 JWT | ✅ | **登出**（B2）：body `{refreshToken}` 撤**单个** grant（幂等）；带 `Authorization: Bearer <jwt>` 且无 body → 撤**该账号全部** grant（全设备登出，返回 `{revokedCount}`）。refresh 相关操作成功才审计 |
 | 2 | `/api/v1/health` | GET | 否 | ✅ | 健康检查 `{data:{status:"ok"}}` |
 | 3 | `/api/v1/chat` | POST | JWT | ✅ | `{text,image?,deviceId?,mode?,stream?}` → `{data:{reply}}`；`stream:true` 时经 WS 触发流式。`image` 为 base64 data: URI 或 http(s) URL，入视觉路由（design/06）——**真视觉需配 `LLM_VISION_MODEL`/凭据，无凭据时降级为主模型直接看图或视觉·OCR 工具文本描述**；`deviceId` 为**客户端生成的具体端标识**（design/16 §4.5，如 `web:chrome:a1b2c3`，可选），落库到消息、便于主人知道从哪个端发来；`mode` 为**行为模式**（design/01 §3 / design/16 §5.1，如 `chat`/`code`/`home`/`docs`/…，可选），随该轮次落库——IM 恒 `chat`、缺省回落 `chat`，供前端按模式渲染气泡（仅 `chat` 才解析 `<p>` 拆气泡）。**会话编排（design/15）**：非流式且该会话「正忙」时**不阻塞**，返回 `202` `{data:{queued:true,queueDepth}}`（稍后按上下文续接）；待处理队列满时返回 `409` `{error:{code:"chat_busy"}}` |
-| 4 | `/api/v1/sessions` | GET | JWT | ✅ | `{data:[session...]}`。**会话持久化（design/16）**：注入 HistoryStore 后返回持久化会话元数据 `{data:[{id,type("main"|"sub"),title?,createdAt,pinned,unreadCount,lastMessage?}]}`（**排序（D5）：`pinned=true` 优先，其次主会话 `id="web"` 恒在前，再按 `createdAt` 升序**；次级 `web:<uuid>`；`pinned` 恒返回 bool；**`unreadCount`（D4）恒返回整数**——该会话中 `createdAt >` 已读游标的消息条数（0 = 无未读），与 `lastMessage` **同一条 SQL 派生**、无 N+1；`lastMessage` 为**最后一条消息预览** `{content,role(user|assistant),createdAt}`，content 折叠空白截前 60 rune，空会话省略）；未注入时退化回渠道会话列表 |
-| 5 | `/api/v1/sessions` | POST | JWT(owner/admin) | ✅ | **新建次级会话** → `201 {data:{sessionId}}`（`sessionId="web:<uuid>"`）；未注入 HistoryStore 回 `501 not_implemented` |
-| 6 | `/api/v1/sessions/{id}/messages` | GET | JWT(owner/admin) | ✅ | **热分页拉历史**：`?limit=&before=&platform=&after=`（A5）默认 `limit=50`（上限 200）。**`before`**=上一页最旧 `createdAt`（毫秒），按时间**倒序**；**`after`**=<`createdAt` 毫秒>，按时间**升序**返回 `created_at > after` 的消息（**正向增量**，客户端把上次看到的 `createdAt` 当游标补断线期间漏的，解决重连只回放 50 条的缺口）；**`after` 与 `before` 互斥**，同传回 `400`；负数/非数字回 `400`。`platform` 为**可选**来源平台过滤（design/16 §4.4）——Web 端不传（=全量共享主会话），IM 适配器传**本平台**（如 `telegram`）只拉本渠道消息；`deviceId` 为**客户端具体端标识**；`senderName` 为**第三方发送者昵称**；**`q`**（D2）=**会话内内容搜索**（大小写不敏感 ASCII LIKE，`%`/`_`/`\` 已转义为字面量），仍按时间**倒序**、`before`/`limit` 同分页语义；`q` 与 `after` **互斥**（同传 `400`），空 `q` 视为未传（走普通分页），搜索**严格限定在 `{id}` 会话内**（绝不跨会话，群聊/陌生人隔离会话不会外泄）；非法 `limit`/`before`/`after` 回 `400`；未注入 HistoryStore 回 `501` |
+| 4 | `/api/v1/sessions` | GET | JWT | ✅ | `{data:[session...]}`。**会话持久化（design/16）**：注入 HistoryStore 后返回持久化会话元数据 `{data:[{id,type("main"|"sub"),title?,createdAt,pinned,unreadCount,lastMessage?,personaId?}]}`（**排序（D5）：`pinned=true` 优先，其次主会话 `id="web"` 恒在前，再按 `createdAt` 升序**；次级 `web:<uuid>`；`pinned` 恒返回 bool；**`unreadCount`（D4）恒返回整数**——该会话中 `createdAt >` 已读游标的消息条数（0 = 无未读），与 `lastMessage` **同一条 SQL 派生**、无 N+1；`lastMessage` 为**最后一条消息预览** `{content,role(user|assistant),createdAt}`，content 折叠空白截前 60 rune，空会话省略；**`personaId`（v0.42，可选）**=该会话绑定的角色 id（design/22 §2/§4.5），**空/缺省 = 继承全局默认角色**（`owner.yaml:defaultPersona`），客户端据此渲染激活会话的角色名/头像）；未注入时退化回渠道会话列表 |
+| 5 | `/api/v1/sessions` | POST | JWT(owner/admin) | ✅ | **新建次级会话** → `201 {data:{sessionId,personaId?}}`（`sessionId="web:<uuid>"`）。body **可选**（可完全省略或空 body）：`{personaId?}`（v0.42）在创建时就把新会话绑到该角色，等价于随后 PATCH 一次（design/22 §2：渠道级只作"新会话的初始角色提供者"）；`personaId` 为**未知角色**回 `400 bad_request`；省略/空 = 不绑（`persona_id=''`，继承全局默认）；**`personaId` 非空时响应回显它**（省略时响应形状与 v0.41 完全一致）；未注入 HistoryStore 回 `501 not_implemented`；注入了**不支持角色绑定**的 HistoryStore 且显式传 `personaId` 时也回 `501`（不假装写入） |
+| 6 | `/api/v1/sessions/{id}/messages` | GET | JWT(owner/admin) | ✅ | **热分页拉历史**：`?limit=&before=&platform=&after=`（A5）默认 `limit=50`（上限 200）。**`before`**=上一页最旧 `createdAt`（毫秒），按时间**倒序**；**`after`**=<`createdAt` 毫秒>，按时间**升序**返回 `created_at > after` 的消息（**正向增量**，客户端把上次看到的 `createdAt` 当游标补断线期间漏的，解决重连只回放 50 条的缺口）；**`after` 与 `before` 互斥**，同传回 `400`；负数/非数字回 `400`。`platform` 为**可选**来源平台过滤（design/16 §4.4）——Web 端不传（=全量共享主会话），IM 适配器传**本平台**（如 `telegram`）只拉本渠道消息；`deviceId` 为**客户端具体端标识**；`senderName` 为**第三方发送者昵称**；**`personaId`（v0.42，可选）**=**该消息说话时的角色 id**（design/22 §7-5：会话可在保留上下文的前提下换角色，故每条消息都记"谁说的"；assistant 消息 = 生成它的角色，user 消息 = 当回合角色；**空 = 全局默认角色**，即 v0.42 之前的全部历史消息），客户端据此按角色渲染名字/头像；**`q`**（D2）=**会话内内容搜索**（大小写不敏感 ASCII LIKE，`%`/`_`/`\` 已转义为字面量），仍按时间**倒序**、`before`/`limit` 同分页语义；`q` 与 `after` **互斥**（同传 `400`），空 `q` 视为未传（走普通分页），搜索**严格限定在 `{id}` 会话内**（绝不跨会话，群聊/陌生人隔离会话不会外泄）；非法 `limit`/`before`/`after` 回 `400`；未注入 HistoryStore 回 `501` |
 | 6a | `/api/v1/messages/{id}` | PATCH | JWT(owner/admin) | ✅ | **编辑单条消息**（D3）：body `{content}`（非空、≤4000 rune，空/纯空白/超长回 `400`）→ **`{data:<消息DTO>}`**（`data` **直接就是**更新后的完整消息 DTO，含 `id/sessionId/role/content/.../createdAt`，**无 `message` 包一层**；**只改 `content`**，role/时间戳/平台保持不变）；消息不存在回 `404 not_found`；未注入 HistoryStore 回 `501`。**成功后广播下行 `message_edited`**（§3.8，账号其它端免刷新同步）。**重发不单独设端点**——客户端用「编辑后的内容再 `POST /chat`」即可（避免重复轮次语义） |
 | 6b | `/api/v1/messages/{id}` | DELETE | JWT(owner/admin) | ✅ | **删除单条消息**（D3）→ `{data:{deleted:<id>}}`；不存在回 `404 not_found`；未注入 HistoryStore 回 `501`。**成功后广播下行 `message_deleted`**（§3.8，账号其它端按 `id` 移除） |
 | 7 | `/api/v1/sessions/{id}` | DELETE | JWT(owner/admin) | ✅ | **删除次级会话及其消息** → `{data:{deleted:<id>}}`；主会话不可删回 `403 forbidden`；未注入 HistoryStore 回 `501` |
-| 8 | `/api/v1/sessions/{id}` | PATCH | JWT(owner/admin) | ✅ | **会话元数据更新**（A4 改名 + D5 置顶）：body `{title?,pinned?}`（**至少一个字段**，都缺回 `400`）。`title` trim、≤80 rune，空/超长回 `400`；`pinned` 为 bool（置顶/取消，主会话与次级会话均可）。响应只回显**本次变更**的字段：`{data:{id,title?}}` / `{data:{id,pinned?}}` / 两者都改则都有（**title-only 保持 A4 原 `{id,title}` 形状**）；不存在回 `404`；主会话(`id="web"`)可改名/置顶但不可删；未注入 HistoryStore 回 `501`。另：会话**首条用户消息到达时自动命名** title（取前 20 rune 折叠空白；纯空白回落 `主会话`/`次级会话`），列表不再空名 |
+| 8 | `/api/v1/sessions/{id}` | PATCH | JWT(owner/admin) | ✅ | **会话元数据更新**（A4 改名 + D5 置顶 + v0.42 选角）：body `{title?,pinned?,personaId?}`（**至少一个字段**，都缺回 `400`）。`title` trim、≤80 rune，空/超长回 `400`；`pinned` 为 bool（置顶/取消，主会话与次级会话均可）；**`personaId`**（v0.42）重新绑定该会话的角色——**显式 `""` = 解绑**（回到"继承全局默认"），未知角色 id 回 `400`，主会话与次级会话均可改（design/22 §4.5）；**改角色不动已存会话内容**：历史消息仍带各自"说话时的角色"（`chat_messages.persona_id`），只有**下一回合**起用新角色的提示词/记忆域/情绪/思考预算。响应只回显**本次变更**的字段：`{data:{id,title?}}` / `{data:{id,pinned?}}` / `{data:{id,personaId?}}` / 多项同改则都有（**title-only 保持 A4 原 `{id,title}` 形状**）；不存在回 `404`；主会话(`id="web"`)可改名/置顶/选角但不可删；未注入 HistoryStore 回 `501`（不支持角色绑定的 HistoryStore 在 `personaId` 路径也回 `501`）。另：会话**首条用户消息到达时自动命名** title（取前 20 rune 折叠空白；纯空白回落 `主会话`/`次级会话`），列表不再空名 |
 | 8a | `/api/v1/sessions/{id}/read` | POST | JWT(owner/admin) | ✅ | **推进已读游标**（D4 / Android 协同 B3）：body `{before?}`——`before` 为**可选**的毫秒 Unix 时间戳，**缺省（或空 body）= 现在**，即「我看到的都算已读」。→ `200 {data:{sessionId,readAt}}`（`readAt` 为推进后的游标毫秒）。**判定**：`createdAt <= readAt` 的消息算已读（列表 `unreadCount` 只数 `createdAt > readAt` 的）；**语义**：**会话级单一游标、单 owner 账号**——读一处 = **该账号所有端已读**（不做 per-device 游标，与「同一账号所有浏览器都属于同一 owner」一致）；**只前进不后退**（SQL `read_at = MAX(read_at, before)`），所以乱序/并发/重试请求幂等安全、绝不会把已读变回未读。`before` 为 `0`/负数/非数字、或 body 不是 JSON 对象 → `400`；未知会话（含隔离 `sess-xxx`，不在 `chat_sessions`）→ `404`；未注入 HistoryStore → `501 not_implemented`。**成功后广播下行 `session_read`**（§3.9）让同账号其它端清红点；**失败路径不广播**。**升级回填**：迁移 `0010` 把既有会话游标回填为「该会话现有最新消息时间」，升级当天不误报未读 |
 | 9 | `/api/v1/personas` | GET | JWT | ✅ | `{data:[persona...]}` |
 | 10 | `/api/v1/audio/transcribe` | POST | JWT(owner) | ✅ | **语音→文本**：body `{audio:"<base64>",format?,deviceId?}` → `{data:{text, provider?}}`（走后端 STT，百炼 `qwen-audio-3.0-asr-flash`；**当结果为空文本/silent 降级时响应体带 `provider`**（如 `"silent"`，非空文本省略），客户端据此提示「没识别到声音」） |
@@ -110,7 +110,7 @@
 - Web 端镜像实现在 `frontend/web/src/lib/enums.ts`（`labelFor(kind, value)` 对未知值返回原值），权威仍以本端点为准。
 - **反漂移保证（后端）**：后端有测试断言「每个内置适配器的 `Name()` 都在 `platforms` 表内」「`moods` 与 persona 情绪状态机的内置状态一致」「`modes` 与前端 `MODES` 九模式一致」——漏登记即 CI FAIL，客户端拿到的表不会滞后于代码。
 
-> **契约版本 `v0.41`**（新增可选字段，向后兼容；本条标记此前停留在 `v0.39`，本轮随人格 `thinking` 字段一并对齐到最新版本号）。
+> **契约版本 `v0.42`**（多角色并存 + 按会话选角：**新增两个可选字段（会话/消息 `personaId`）+ 两个可选请求字段（`POST /sessions` body、`PATCH /sessions/{id}` 的 `personaId`）**，向后兼容）。
 
 ## 2. REST 端点（管理，`/api/v1/admin/*`）
 
@@ -142,7 +142,7 @@
 | # | 端点 | 方法 | 状态 | 说明 |
 |---|------|------|:---:|------|
 | 1 | `/api/v1/admin/personas` | GET | ✅ | 人格列表 |
-| 2 | `/api/v1/admin/sessions` | GET | ✅ | 持久化会话列表（主会话 + 次级会话，design/16 §2）；未注入 HistoryStore 时回退渠道会话视图 |
+| 2 | `/api/v1/admin/sessions` | GET | ✅ | 持久化会话列表（主会话 + 次级会话，design/16 §2）；未注入 HistoryStore 时回退渠道会话视图。**v0.42 起每项含可选 `personaId`**（与会话级选角同源，见 §1 行 4） |
 | 3 | `/api/v1/admin/memories` | GET | ✅ | 记忆列表（手动添加/检索已实现；编辑/删除/衰减随 M10 扩展） |
 | 4 | `/api/v1/admin/plugins` | GET | ✅ | 插件/能力列表（含 MCP/渠道） |
 | 5 | `/api/v1/admin/plugins/policy` | POST | ✅ | 写工具策略（owner-only，审计） |
@@ -201,7 +201,7 @@
 - `POST /admin/plugins/install`（**owner-only + 审计 `plugin.install`**）body `{kind:"mcp",name,config:{transport:"stdio|http|sse",endpoint?|command?,args?,apiKey?,env?}}` → `200 {data:{installed:true,name,kind:"mcp",transport,toolCount}}`。**v1 只装 MCP server**（单二进制无法热装 Go 插件）：真实 connect+discover，把发现的工具**热注册**进 capability registry（下次模型请求即注入，无需重启）→ 落盘 `plugins.json`（本地、gitignore、0600，`apiKey` 写入但**永不回显/不落日志**）→ 持有 live server 供后续刷新/卸载。**同名重复安装 = 刷新**（先卸旧再装新，失败回滚旧）。校验：`name` 必填、`kind` 非 `mcp` 回 `400`、transport 非法/`stdio` 缺 `command`/`http|sse` 缺 `endpoint` 回 `400`；**连接/发现/注册失败回 `502 plugin_install_failed` 且不落盘**（诚实，不静默装一半）。未注入 plugin manager 回 `501 not_implemented`。
 - `POST /admin/plugins/uninstall`（**owner-only + 审计 `plugin.uninstall`**）body `{name}` → `200 {data:{name,uninstalled:true,kind:"mcp"}}`（已装 MCP：`Unregister` 移除其工具 + close + 删 `plugins.json` 条目；**非 MCP/普通能力**走原 `registry.Remove`，返回 `{data:{name,uninstalled:true}}`）；未命中回 `404`。
 - `POST /admin/memories` body `{personaId?,content,scope?}` → `201 {data:{id,scope,text}}`。**手动添加记忆**（owner 私聊直写）；`scope` ∈ `user|persona|project`，缺省 `persona`（与「记住…」同路径）；无效非空 `scope` 回 `400`；未注入 `memory.Store` 回 `501`。
-- `POST /admin/memories/search` body `{query,personaId?,topK?}` → `200 {data:{query,personaId,semantic,hits:[{id,scope,text,score}]}}`。真实检索（keyword×衰减）；**语义/向量路径**需主会话注入 vector index（`semantic` 当前恒 `false`，诚实反映未接向量器）。
+- `POST /admin/memories/search` body `{query,personaId?,topK?}` → `200 {data:{query,personaId,semantic,hits:[{id,scope,text,score}]}}`。真实检索（keyword×衰减）；**语义/向量路径**需主会话注入 vector index（`semantic` 当前恒 `false`，诚实反映未接向量器）。**`personaId` 省略时（v0.42 起）回落到库里注册的默认角色**（`default` 标记的那个 character → 其 persona），**不再写死 `"cyrene"`**；若既未传 `personaId` 又没有任何默认角色 → `400 bad_request`（诚实报错，而不是拿一个不可能命中的 id 去查）。
 - `GET /admin/sessions/{id}/export` → `200 {data:{session:{platform,channelId,sessionId,actorRole,owner,isGroup,memWritable}}}`；`404`。当前导出会话身份元数据（完整消息转录由 M10 提供）。
 
 **系统设置契约**（`POST /api/v1/admin/system/*`，均 **owner-only**，审计；成功 `{data}` / 失败 `{error:{code,message}}`）：
@@ -239,7 +239,7 @@
 - **握手**: `ws://<host>:8080/ws/chat?token=<JWT>` 或 `Authorization: Bearer`；未认证在握手前回 `401` JSON。
 - **下行（服务端→客户端）**: 经 bus 广播 `{type:"<event>", data:..., turnId?, seq?, sessionId?}`（`turnId`/`seq` 为流式关联字段，见 §3.1；`sessionId` 为**会话持久化（design/16）新增**，能确定会话的事件带上，供客户端按激活会话过滤；**v0.36 起结构化流帧 `message.*` / `thinking.*` / `tool_call.*` / `tool_execution.update` 也带 `sessionId` + `turnId`**——多会话并发流式时客户端据此把 delta 路由到激活会话，见 §3.1）——`message.start/delta/end` / `thinking.start/delta/end` / `tool_call.start/delta/end` / `tool_execution.update`（结构化流，design/04 §1.1），以及向后兼容的 `stream_chunk` / `stream_end` / `thinking`(思维链) / `mood`(情绪变化，见 §3.7) / `reminder` / `device_update` / `tool_used`(工具回显) / `subagent_event` / `graph_update` / **`message_persisted`**（会话持久化增量，见 §3.3）/ **`message_edited`**、**`message_deleted`**（消息编辑/删除增量，见 §3.8）/ **`session_read`**（已读游标推进，见 §3.9）。**会话编排状态（design/15，均为广播，`data.sessionId` 区分会话）**：`session_busy` / `pending_ack` / `pending_drain` / `session_idle` / `session_interrupted` / `pending_full`（见 §3.2）。语音回复走 `voice_output`（定向回请求连接，非广播）。
 
-  > **`history` 回放事件（design/16，新增）**：WS 握手升级成功后、该连接下一帧即收到 `{type:"history", sessionId:"web", data:{messages:[{id,sessionId,role,content,mode?,mood?,image?,platform?,deviceId?,createdAt}]}}`——回放主会话最新 50 条（`thinking` 已剥离，不泄给非 owner；默认主会话，次级会话由客户端按激活会话走 `GET /sessions/{id}/messages` 拉取）。客户端据此在重连/新开连接后补全上下文。消息体含 `senderName?`（第三方昵称，design/16 §4.6，主人私聊为空）。
+  > **`history` 回放事件（design/16，新增）**：WS 握手升级成功后、该连接下一帧即收到 `{type:"history", sessionId:"web", data:{messages:[{id,sessionId,role,content,mode?,mood?,image?,platform?,deviceId?,personaId?,createdAt}]}}`——回放主会话最新 50 条（`thinking` 已剥离，不泄给非 owner；默认主会话，次级会话由客户端按激活会话走 `GET /sessions/{id}/messages` 拉取）。客户端据此在重连/新开连接后补全上下文。消息体含 `senderName?`（第三方昵称，design/16 §4.6，主人私聊为空）与 `personaId?`（v0.42，说话时的角色，design/22 §7-5，空 = 默认角色）。
 
 ### 3.1 结构化流事件（`message.*` / `thinking.*` / `tool_call.*` / `tool_execution.*`）
 - **事件壳**：`{type, sessionId?, turnId?, seq?, data}`, `data` 为**类型化结构**（非 `any`）。`seq` 为 hub 级单调递增序号，供客户端将一次突发的流式事件排序关联。**`sessionId` 为事件所属会话、`turnId` 为该轮助手回合 id（均 v0.36 起带上）**：`sessionId` 由 loop 在回合边界注入（模型适配器在 loop 之下、不感知会话，恒留零值；loop 外无会话上下文的事件该字段为空），`turnId` 由网关每个回合新生成并挂进运行上下文——同一会话同时只有一个 in-flight 回合，故**同轮内所有帧的 `turnId` 一致**。客户端据此把 `message.delta` / `thinking.delta` / `tool_call.*` / `tool_execution.update` 过滤到 `sessionId === activeSessionId` 的会话，忽略非激活会话的帧（多会话并发流式不再串话）。
@@ -268,7 +268,7 @@
 
 ### 3.3 消息持久化增量事件（`message_persisted`，design/16）
 - **触发**：每一条 user / assistant 消息**落库后**由编排层广播——Web 主会话路径走 `persistUserMessages`/`persistAssistantReply`，**IM 渠道主人私聊**（design/16 §4.4）由 channelbridge 把消息**落主会话 `web`**（带 `platform` 标记）后复用**同一** `message_persisted` 广播（同一 hub 的 `BroadcastPersisted`），保证 Web 端实时镜像 IM 消息。
-- **载荷**：`{type:"message_persisted", sessionId, data:{message:{id, sessionId, role, content, mode?, mood?, image?, platform?, deviceId?, senderName?, createdAt}}}`——`role` ∈ `user|assistant`；`id` 为**后端生成的消息 id**（客户端据此去重）；`platform` 为**来源平台**（`web` 或渠道如 `telegram`/`weixin-ilink`/`qq-obv11`）；`deviceId` 为**具体端/客户端标识**（design/16 §4.5，如 `web:chrome:a1b2c3` / `weixin-ilink:conf0:wx_uid`）；`senderName` 为**第三方发送者昵称**（design/16 §4.6，群聊/陌生人消息带，主人私聊为空，`omitempty`）；`thinking` 已剥离（design/16 §6）。
+- **载荷**：`{type:"message_persisted", sessionId, data:{message:{id, sessionId, role, content, mode?, mood?, image?, platform?, deviceId?, senderName?, personaId?, createdAt}}}`——`role` ∈ `user|assistant`；`id` 为**后端生成的消息 id**（客户端据此去重）；`platform` 为**来源平台**（`web` 或渠道如 `telegram`/`weixin-ilink`/`qq-obv11`）；`deviceId` 为**具体端/客户端标识**（design/16 §4.5，如 `web:chrome:a1b2c3` / `weixin-ilink:conf0:wx_uid`）；`senderName` 为**第三方发送者昵称**（design/16 §4.6，群聊/陌生人消息带，主人私聊为空，`omitempty`）；**`personaId`（v0.42，`omitempty`）=该消息说话时的角色 id**（design/22 §7-5；空 = 全局默认角色，即升级前的全部历史），客户端据此按角色渲染名字/头像；`thinking` 已剥离（design/16 §6）。
 - **注：群聊/陌生人（非主人）消息**只在**该 IM 适配器日志界面**以消息流显示，**不**经 `message_persisted` 进 Web 主会话（design/16 §4.6 §3-4）；该日志流由 `GET /api/v1/admin/channels/{platform}/messages` 拉取，落库后另经 `channel_persisted`（§3.4）实时推送。
 - **客户端处理**：仅当 `data.message.sessionId === activeSessionId`（激活会话）时处理；按 `id` upsert——本端已预建的**同 role 乐观气泡**（本地 `uid` 无后端 `id`）被**归一**（`uid` → 后端 `id`），异端无本地气泡则直接追加，两者最终收敛为**同一条 `id` 相同的消息**，「A 发消息、A 与 B 都无需刷新且各出现一次」。
 
@@ -325,8 +325,9 @@
 3. **带端标识**（可选但推荐）：每条消息/请求可带 `deviceId`（见 §4.3），让她知道你从哪个端来。
 
 ### 4.2 会话与消息用法（聊天）
-- **列出会话**：`GET /api/v1/sessions` → `[{id,type:"main"|"sub",title?,createdAt,pinned,unreadCount,lastMessage?}]`。**排序：置顶会话（`pinned=true`）最前，其次主会话 `id="web"`**（她与你的主线，最大化继承上下文），再按创建时间升序；次级 `web:<uuid>` 由 `POST /api/v1/sessions` 新建（临时小事/专业问题，独立上下文回溯）。
-- **改名 / 置顶**：`PATCH /api/v1/sessions/{id}` body `{title?}`（≤80 rune）或 `{pinned?:bool}`（至少一个字段）→ `{data:{id,title?,pinned?}}`（只回显变更字段）。
+- **列出会话**：`GET /api/v1/sessions` → `[{id,type:"main"|"sub",title?,createdAt,pinned,unreadCount,lastMessage?,personaId?}]`。**排序：置顶会话（`pinned=true`）最前，其次主会话 `id="web"`**（她与你的主线，最大化继承上下文），再按创建时间升序；次级 `web:<uuid>` 由 `POST /api/v1/sessions` 新建（临时小事/专业问题，独立上下文回溯）。**`personaId`（v0.42）=该会话绑定的角色**；空/缺省 = **继承全局默认角色**，客户端渲染激活会话的名字/头像用它（后端唯一真源是 `chat_sessions.persona_id`，localStorage 之类只作缓存）。
+- **选角 / 换角色（v0.42）**：`POST /api/v1/sessions` body `{personaId?}` 在**新建时**就绑角色；已存在的会话用 `PATCH /api/v1/sessions/{id}` body `{personaId}` 重新绑定（显式 `""` 解绑回"跟随默认"）。**换角色保留上下文**：历史消息逐条带自己的 `personaId`，只有**下一回合**起提示词/记忆域/情绪/思考预算换成新角色（design/22 §7-5）。**记忆按角色隔离**：不同角色的会话各记各的，同一角色的多个会话互相可见（design/22 §3 口径 1）；群聊/陌生人会话仍**只读**、且强制默认角色。
+- **改名 / 置顶 / 选角**：`PATCH /api/v1/sessions/{id}` body `{title?}`（≤80 rune）或 `{pinned?:bool}` 或 `{personaId?:string}`（至少一个字段）→ `{data:{id,title?,pinned?,personaId?}}`（只回显变更字段）。
 - **未读 / 已读游标（D4）**：列表项的 **`unreadCount`** 直接用于会话列表红点（恒返回整数，0 = 无未读）。客户端进入会话、或滚到底看到最新消息后调用 **`POST /api/v1/sessions/{id}/read`**：body `{"before":<毫秒>}`（如「本次已渲染的最新一条的 `createdAt`」），或**省略 body** = 标记到**现在**。后端**只前进**地推进该会话**唯一**游标（单 owner 账号：读一处 = 所有端已读），并广播 `session_read`（§3.9）——同账号其它端**免刷新**清红点。列表 → 读 → 再看列表即可自洽（漏收广播的端下次拉列表自然收敛）。
 - **拉取激活会话历史**：`GET /api/v1/sessions/{id}/messages?limit=50&before=<ms>&platform=&q=`。
   - **热分页**：`limit` 默认 50（上限 200），`before` = 当前最旧一条的 `createdAt`（毫秒），向上翻页。`platform` 可选（IM 适配器传本平台只拉本渠道；Web/通用客户端不传 = 全量共享主会话）。
@@ -353,6 +354,7 @@
 - 语音：上行 `voice_input`（base64 音频或已转写 text），下行 `voice_output`（合成音频 base64 + text）。
 
 ## 5. 变更记录
+- `v0.42`（**多角色并存 + 按会话选角**，对客户端**新增可选字段/可选请求字段**，向后兼容；design/22 批次 1 = 后端会话级绑定）：① **`chat_sessions` 新增 `persona_id TEXT NOT NULL DEFAULT ''`、`chat_messages` 新增 `persona_id TEXT NOT NULL DEFAULT ''`**（同一迁移 **0011**，down 可逆，**不回填**）。`''` **= 继承全局默认角色**（`owner.yaml:defaultPersona`），所以**既有一切行升级后行为逐字节不变**，且默认角色改名后这些行跟着变（design/22 §4.7/§7-6）。② **`GET /api/v1/sessions` 每项新增可选 `personaId`**（=会话绑定角色）；**消息 DTO（REST `GET /sessions/{id}/messages`、WS `history` 回放、`message_persisted`/`message_edited` 广播）新增可选 `personaId`**（=**说话时的角色**，design/22 §7-5）。③ **`POST /api/v1/sessions` body 新增可选 `{personaId}`**（创建即绑定；未知角色 `400`；响应仅在非空时回显 `personaId`，故**省略时响应形状与 v0.41 完全一致**）；**`PATCH /api/v1/sessions/{id}` body 新增可选 `{personaId}`**（重新绑定，**显式 `""` 解绑**，未知角色 `400`；只回显变更字段）。④ **回合语义**：角色决定**系统提示词 / 记忆命名空间 / 情绪与好感度 / 思考预算**四者**同源**解析（design/22 §4.2），换角色**保留上下文**、**不动已存消息**，**下一回合**起生效；**记忆口径 = 保持 persona 隔离**（design/22 §3）：不同角色的会话互不浮现，同角色的多个会话互相可见。⑤ **请求级覆盖（每次发送临时指定角色）本批未实现**（design/22 §2 裁决规则 1 仍待批次 2/后续）；**渠道级绑定（IM 账号/群默认角色）本批未实现**（design/22 §4.4 批次 2），故 IM 路径仍按默认角色解析。⑥ **契约内新增内部读接口**：网关经窄接口类型断言读取 `history.Store.SessionPersona/SetSessionPersona/NewSubSessionFor`（注入的 HistoryStore **不支持**角色绑定时，`personaId` 写路径回 `501` 而非假成功）。
 - `v0.41`（**人格 `thinking` 配置 + 推理旋钮按 provider 映射**，对客户端**新增一个可选请求字段**，向后兼容）：① `POST /admin/personas` / `PUT /admin/personas/{id}` body 新增可选 **`thinking`** 对象 `{budgetTokens?,effort?,showToUser?,mode?}`（design/01 §2.1），原样写入并持久化到 `configs/personas/<id>.yaml` 的 `thinking` 节；非法 `mode`/负预算回 **`400 bad_request`**；**`PUT` 省略该对象时保留已存 `thinking`**（旧面板/脚本不会抹掉它）；该字段只描述**呈现/资源**，不构成能力边界。② **`showToUser` 语义**：**缺省 = 照常把 `thinking.*` 流帧推给客户端**（现行为），显式 `false` = 仅落库/剥离语义不变、**不推帧**（展示与落库解耦）。③ **服务端推理映射**（对客户端透明，仅影响上游请求）：Anthropic 系在 persona 配置 `budgetTokens`/`mode: on` 时发 `thinking:{type:"enabled",budget_tokens:N}`，并**保证 `budget_tokens + 正文留量 ≤ max_tokens`**（不足则抬高 `max_tokens` 并记 WARN，绝不把正文吃空）；OpenAI 兼容系按**识别到的厂商白名单**校验 `reasoning_effort`（OpenAI 系 `none…max`、DeepSeek 仅 `low/high/max`），非法值**降级到最近一档并记 WARN**；**未知 provider/未识别模型、以及 Qwen 的 `enable_thinking` 硬开关（协议无统一 wire 形状）** 一律记 **WARN（含 provider/字段/取值）并保持请求不变**，绝不静默无效。详见 design/04 §3.2。
 - `v0.40`（**`viewer` 角色真正接线：只读监控档**，对客户端**收紧/放宽若干 admin 读的鉴权**，无端点/字段形状变更）：此前 `viewer` 只是常量（`internal/auth` 的 `RoleViewer` 注释写着「只读 dashboard/logs/monitoring」）而**从未接线**——管理侧 24 条 GET 全走 owner/admin，`viewer` 一条都读不到（**全 403**）。本版新增第四道门 `viewerAuth = owner+admin+viewer`，并把 **12 条只读监控 GET** 从 owner/admin 放宽到 owner/admin/**viewer**：`GET /admin/personas`、`/admin/sessions`、`/admin/plugins`、`/admin/plugins/installed`、`/admin/channels`、`/admin/iot`、`/admin/automations`、`/admin/rag`、`/admin/observability/metrics`、`/admin/observability/trace`、`/admin/observability/logs`、`/admin/notifications`。**明确不放给 viewer**（含凭据获取路径、他人数据、完整消息/导出明文、审计流水，或 `admin` 也不给）：`GET /admin/memories`、`/admin/llm`、`/admin/users`、`/admin/backthink`、`/admin/observability/audit`、`/admin/channels/messages`、`/admin/channels/{platform}/messages`、`/admin/sessions/{id}/export`、`POST /admin/rag/query`（这 9 条 owner/admin）以及其余 **35 条 owner-only**（全部写操作 + `login-qr`/`login-status`/`view`/`friends`/渠道连接与配置/`plugins/*`/`users/*`/`system/*`）。**匿名**：任意 admin 路由仍 `401`（fail-closed）。**向后兼容**：`owner`/`admin` 语义不变（放行集合是超集），仅 `viewer` 的可见面从「全 403」变为 12 条只读监控；不依赖 `viewer` 的客户端行为不变。完整分档见 §2.0「管理侧权限矩阵」。
 - `v0.39`（**微信 iLink 会话被拒可见化 + 不再假 OK**，对客户端**新增两个可选字段、一处错误码**，向后兼容）：① **`GET /api/v1/admin/channels` 每平台行新增可选 `needsRescan`（bool，`omitempty`）+ `lastError`（string，`omitempty`）**——仅当适配器**真的**要求重新授权时出现（今天只有微信 iLink 返回 `errcode=-14` 这一种），取值来自适配器新增的**可选能力接口** `RescanRequired() (bool, string)`，网关**经类型断言**读取（主 `PlatformAdapter` 契约**不变**；未实现该能力的平台字段**缺省不出现**）。用途：把「需要重新扫码」与「主人自己关掉的未连接」区分开——后者仅 `connected:false`。② **`POST /admin/channels/open`** 对「iLink 已拒绝该会话」回 **`409 session_rejected`**（message 明确要求用「扫码登录」重新绑定），**不再**吞掉错误回 200；`409 needs_login`（尚无 token，v0.8 起）不变。③ **适配器行为**：iLink `errcode=-14` 进入**显式被拒态**——`IsConnected()` 恒 `false`；`Connect()` 返回被拒错误（**不再**对被拒会话报成功）；`HealthCheck` 区分「会话被拒」与「未连接」；并以 **`ERROR`** 级日志写明「本次会话已被 iLink 拒绝，需要重新扫码绑定」（只带 `bot_id` 等非敏感标识，**token 永不入日志**）。被拒态在读循环与发送两条路径**都会**置位，并仅在**扫码登录拿到新 token** 或**配置换了新 token**（保存 + 热重载）时清除。④ 扫码登录侧：被拒期间 `login-status` 报 **`failed` + 被拒原因**（**不再**假报 `confirmed`，否则面板会把已作废凭据当成功重新落盘）；`login-qr` 仍可正常出码（**不**回 `already_logged_in`，否则重新扫码这条路被堵死）；`get_bot_qrcode` 不再携带已被拒的 token（否则服务端以「已绑定」应答、**不**发新凭据）。**向后兼容**：只新增可选字段与一处更诚实的错误码；不读新字段、不处理 409 的客户端行为不变（此时面板显示「未连接」，仍可用「扫码登录」恢复）。**语义澄清（本次仅措辞，不改契约形状、不另起版本号——v0.39 尚未被任何客户端采用）**：iLink 的 bot token 是**长期凭据**（实测一个月前扫码得到的 token 仍可用），`errcode=-14` 表示 **iLink 侧拒绝/作废了该会话凭据**，**不是时间性过期**。详见 §2 行 6 与「微信 iLink『会话被拒』契约」。