fix(inbox): 收件箱按**工作区**收窄（三维地址的 path 位此前从未被使用）

用户 12 天前就提过（`552fbc7` 只修了 session_id 那一维），这轮才真修。
用户原话：「难道让一个不在项目工作区的 agentsession 去修工程吗？」

# 缺陷（生产实测，2026-09-26）

在 `mc` 工作区干活的 pi 读收件箱拿到 **200 封，其中 191 封属于
`/home/program/agentmail`** —— 它照着那些信里的断言去改 agentmail 的代码，
把手上的 mc 活丢在一边。用户当场问它「你怎么干着干着修 agentmail 去了？」
（这条对话就在 mc 会话的 jsonl 里）

根因：`ListInboxScoped` 的 WHERE 只有 `m.to_name = $1`（+ 可选 session_id），
**没有任何 workspace 条件**。三维地址 `name@path.session` 的 path 位
在收件箱侧从未生效 —— 那不是"另一种语义"，是没兑现契约。

# 三条守卫全部只覆盖自动转发，防不住这个

| 守卫 | 只覆盖 | 为何无效 |
| --- | --- | --- |
| 会话预算 | `relay != ""` 才扣 | 这批信 relay=0（模型主动发）⇒ 不扣 |
| maxRelayHops=5 | 同上，只数 relay | 同上 ⇒ 不进那个分支 |
| 插件自动转发守卫 | 插件代劳时 | 日志明说"本轮不自动转发" ⇒ 模型自己发的不受管 |

# 服务端

· `ListInboxScoped` / `CountUnreadScoped` / `MarkAllInboxReadForSession`
  三处统一加 `s.workspace = $N`（用会话的 workspace，不用 mails.to_workspace：
  后者是信封字段、可能是抄送或历史遗留；"线索属于哪个工作区"是会话属性）。
  ★ 三处必须是**同一个谓词** —— 列表看不到的信却被"全部标掉"标掉就是静默丢信
  （session_scope_test.go 记过这个形状）。
· **workspace 在 Agent 侧必需，缺了 400**（用户裁定：「不带 workspace 是错误
  发件格式，直接退回！」）。旧语义（不带=全部）正是缺陷本身，不留兼容回退。
· 人类侧**不过滤**（一个人跨工作区，WebUI 按 session_workspace 分组显示）——
  所以"必需"这条约束放在 Handler 而不是 repo 层：它是接口契约，不是数据层不变量。
· 新增 `UnreadWorkspaces`：心跳是**进程级**（一个桥服务所有工作区），没有
  "我的工作区"可言；但只有总数桥不知道去哪个工作区补投 ⇒ 心跳回
  `pending_workspaces` 清单，桥逐个消费。
· 决策载荷补 `workspace`（服务端知道 session→workspace，插件重启后推不出来）。
· `TouchAgentLastSeen` 从 HeartbeatAgent 拆出：middleware 在每个认证请求上都调它，
  而那时工作区还没解析（请求体没读），原来在白算一次 CountUnread。

# 三个插件（pi / opencode / dsh）

· 读类工具带 `workspace`；补投从"读一次全局收件箱"改为**逐工作区**读。
· pi：worker 信封的 `to_workspace` 经闭包递进工具（不是会话文件 header 的 cwd ——
  后者是"会话上次落在哪"，前者是"这封信寄到哪个工作区"）。
· opencode/dsh：插件常驻、信封在 deliverMail 那刻就消费掉了 ⇒ 新增
  `sessionWorkspace` 映射（键与既有 reverseMap 同一把）。
· 修一处真 bug：`UnreadWorkspaces` 原先会返回相对路径工作区（历史库里有
  `workspace='root'`），桥侧实测撞 400（`补投工作区 root 失败`）⇒ 只报可寻址的。

# 实测凭据

· 改前：`pi` 的收件箱 200 封混 3 个工作区（agentmail 191 / TrueAgent 7 / huawei 2）
· 改后：agentmail=100（total 228）、mc=16、TrueAgent=7 —— 各工作区独立
· 不带 workspace ⇒ **HTTP 400**，话术给出可执行步骤
· 桥日志：`rw=/home/newqqagent/plugindev/editdoc-upgrade` —— 终于是别的工作区了
  （改前 78 次 worker 启动**全部**是 `/home/program/agentmail`）

# 判据

· `server/internal/repo/workspace_scope_test.go`（3 条）：
  两向收窄 + **反向对照**（不带时两条都看得到 ⇒ 证明是收窄不是清空）+
  未读数同口径 + 相对路径必须报错
· `plugins/pi-mail-bridge/test/inbox-workspace-scope.test.mjs`（4 条）：接线 +
  取信封而非 cwd + 补投逐工作区 + 判据自检
· dsh 那条 `取不到会话时退回整体收件箱` **改了**：它钉的"退回整体"正是缺陷，
  现在钉"两维各自缺席时各自不带、服务端 400 让错误可见"
· 变异验证：服务端 2 处 + 插件 3 处，全部判红后恢复回绿

全量：server `go test ./...` 绿；三插件 513+340+403 全绿。

server/internal/handler/agents.go

@@ -25,6 +25,11 @@ type registerRequest struct {
 //
 // 字段全可省：旧插件发空心跳，不能因为新增了上报就把它们报错。
 type heartbeatRequest struct {
+	// Workspace 是调用方当前所处的工作区（绝对路径）——**必需**。
+	//
+	// 心跳返回的 pending_mails 按它算：那是桥的补投判据，混了别的工作区
+	// 就会让桥反复重放（见 handler 里那段说明）。
+	Workspace string `json:"workspace"`
 	// PlatformSessions 是平台侧当前的会话快照（按最近活跃排序）。
 	//
 	// 为什么让插件上报而不是 Gateway 反向拉取：当前架构是单向的
@@ -170,17 +175,29 @@ func HeartbeatAgent(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	/*
+		★ pending_mails 是**全局**未读数（跨工作区），而收件箱接口是 worker 级
+		（要求 workspace）。两者不矛盾，是不同层的东西 —— 见 UnreadWorkspaces 注释。
+
+		但只有总数，桥不知道去**哪个**工作区补投（它此前调的是不带收窄的
+		`/mail/inbox`，于是会跨工作区重放）。⇒ 一并给出有未读的工作区清单，
+		桥逐个去读。这也是"心跳返回什么才够用"的答案。
+	*/
+	pendingWorkspaces, _ := repo.UnreadWorkspaces(r.Context(), agentName)
+
+	// 宽容解码（心跳是全站唯一一处容忍未知字段的端点，理由见下面的说明）。
+	var req heartbeatRequest
+	var unknownFields []string
+	if r.ContentLength > 0 {
+		unknownFields, _ = DecodeLenient(r, &req)
+	}
+
 	// 可选的平台会话快照。解不开就当作没带：心跳的主职责是「我还活着」，
 	// 不该因为上报体格式不对就把 Agent 判成离线。
 	//
 	// 但**未知字段必须回报**（resp["unknown_fields"]）：这是全站唯一一处宽容
 	// 解码的端点，若还静默忽略，插件把 `models` 拼成 `modles` 就永远没人知道 ——
 	// 而那与 `attachments` vs `attachment_ids` 是同一种事故形状。
-	var req heartbeatRequest
-	var unknownFields []string
-	if r.ContentLength > 0 {
-		unknownFields, _ = DecodeLenient(r, &req)
-	}
 	syncedSessions := -1 // -1 = 本次未上报
 	if req.PlatformSessions != nil {
 		if err := repo.ReplacePlatformSessions(r.Context(), agentName, req.PlatformSessions); err != nil {
@@ -216,9 +233,10 @@ func HeartbeatAgent(w http.ResponseWriter, r *http.Request) {
 	}
 
 	resp := map[string]interface{}{
-		"status":        "ok",
-		"pending_mails": pending,
-		"stats":         stats,
+		"pending_workspaces": pendingWorkspaces,
+		"status":             "ok",
+		"pending_mails":      pending,
+		"stats":              stats,
 	}
 	if syncedSessions >= 0 {
 		resp["platform_sessions_synced"] = syncedSessions

server/internal/handler/mail.go

@@ -583,6 +583,35 @@ func GetInbox(w http.ResponseWriter, r *http.Request) {
 		}
 	}
 
+	/*
+		★ workspace **必需**（用户裁定：「不带 workspace 是错误发件格式，直接退回！」）。
+
+		# 为什么是 400 而不是"退回旧语义"
+
+		旧语义（不带 = 列该 Agent 全部）正是缺陷本身：`pi` 在 mc 工作区读收件箱
+		拿到 200 封，191 封属于 agentmail 工作区 ⇒ 它照着那些信改 agentmail 的代码。
+		留着旧语义当兜底，等于给这个缺陷留一条随时会被走上去的路。
+
+		三维地址 `name@path.session` 的 path 位本来就该参与寻址 —— 收件箱侧此前
+		完全没用它。现在要求调用方说清自己在哪个工作区，服务端据此收窄。
+
+		★ 为什么服务端**不该**自己去推调用方的工作区：
+		  它是每个 worker 的 cwd（会随回合变），服务端拿不到可靠来源。
+		  让调用方声明、服务端只当过滤条件用（不做鉴权依据）——
+		  与 session_id 那条同构：声明错了只影响自己看到什么，越权不了别人。
+	*/
+	workspace := strings.TrimSpace(r.URL.Query().Get("workspace"))
+	if workspace == "" {
+		Error(w, http.StatusBadRequest,
+			"缺少 workspace：收件箱按工作区收窄（三维地址 name@path.session 的 path 位）。"+
+				"请带上你所处工作区的绝对路径，例如 &workspace=/home/program/agentmail")
+		return
+	}
+	if !strings.HasPrefix(workspace, "/") {
+		Error(w, http.StatusBadRequest, "workspace 必须是绝对路径，收到: "+workspace)
+		return
+	}
+
 	// 可选会话收窄：桥的 read_inbox 会带上自己那条会话。
 	//
 	// 不带 = 整个 Agent 的收件箱（旧语义，浏览器/脚本仍可用）；带了就只列这条线索 ——
@@ -598,7 +627,7 @@ func GetInbox(w http.ResponseWriter, r *http.Request) {
 		sessionID = id
 	}
 
-	mails, err := repo.ListInboxScoped(r.Context(), agentName, status, limit, sessionID)
+	mails, err := repo.ListInboxScoped(r.Context(), agentName, status, workspace, limit, sessionID)
 	if err != nil {
 		Error(w, http.StatusInternalServerError, "Failed to list inbox")
 		return
@@ -609,7 +638,9 @@ func GetInbox(w http.ResponseWriter, r *http.Request) {
 		ptrs[i] = &mails[i]
 	}
 	fillAttachments(r, ptrs...)
-	total, _ := repo.CountUnread(r.Context(), agentName)
+	// ★ total 必须用**同一个收窄口径**，否则列表与计数自相矛盾
+	//   （桥的补投判据就是 pending_mails = 这个数）。
+	total, _ := repo.CountUnreadScoped(r.Context(), agentName, workspace, sessionID)
 
 	JSON(w, http.StatusOK, map[string]interface{}{
 		"mails": emptySlice(mails),
@@ -698,6 +729,10 @@ func parseInt(s string) (int, error) {
 type markReadRequest struct {
 	// SessionID 可选：带了就只在这条会话内标（见 GetInbox 里那段说明）。
 	SessionID string `json:"session_id"`
+	// Workspace **必需**（仅"全部标掉"那条路）：只标这个工作区的信。
+	// 带上 mail_ids 时不要求 —— 那些 id 是调用方从**已收窄的**列表里原样拿回来的，
+	// 服务端按 id 逐个判归属即可（MarkMailsReadFor 只标真发给它的）。
+	Workspace string `json:"workspace"`
 	// MailIDs 要标记为已读的邮件；省略/为空 = 把收件箱里全部未读标掉。
 	MailIDs []string `json:"mail_ids"`
 }
@@ -728,8 +763,26 @@ func MarkInboxRead(w http.ResponseWriter, r *http.Request) {
 	// 不给 id 就把收件箱里全部未读标掉。
 	// 这是 Agent 最常见的用法：一轮处理完，剩下的都不必再看。
 	if len(req.MailIDs) == 0 {
+		/*
+			★ workspace **必需**，与 GET /mail/inbox 同一条规矩。
+
+			这条路口径更宽（"全部标掉"），缺了工作区会把**别的工作区的未读也标掉** ——
+			而"被别人标掉"正是那封静默丢信的旧缺陷（read_inbox 按会话收窄那次修的
+			就是它，见 session_scope_test.go）。收窄到工作区，同一类错误就没法再发生。
+		*/
+		ws := strings.TrimSpace(req.Workspace)
+		if ws == "" {
+			Error(w, http.StatusBadRequest,
+				"缺少 workspace：全部标已读必须指明工作区（否则会标掉别的工作区的未读）。"+
+					"若是按 id 标记，请直接传 mail_ids")
+			return
+		}
+		if !strings.HasPrefix(ws, "/") {
+			Error(w, http.StatusBadRequest, "workspace 必须是绝对路径，收到: "+ws)
+			return
+		}
 		var sessionID uuid.UUID
-		scope := "all"
+		scope := "workspace"
 		if raw := strings.TrimSpace(req.SessionID); raw != "" {
 			id, perr := uuid.Parse(raw)
 			if perr != nil {
@@ -738,7 +791,7 @@ func MarkInboxRead(w http.ResponseWriter, r *http.Request) {
 			}
 			sessionID, scope = id, "session"
 		}
-		n, err := repo.MarkAllInboxReadForSession(r.Context(), agentName, sessionID)
+		n, err := repo.MarkAllInboxReadForSession(r.Context(), agentName, ws, sessionID)
 		if err != nil {
 			Error(w, http.StatusInternalServerError, "Failed to mark read")
 			return

server/internal/handler/me.go

@@ -218,7 +218,7 @@ func MeGetInbox(w http.ResponseWriter, r *http.Request) {
 		}
 	}
 
-	mails, err := repo.ListInbox(r.Context(), user.Username, status, limit)
+	mails, err := repo.ListInbox(r.Context(), user.Username, status, "", limit)
 	if err != nil {
 		Error(w, http.StatusInternalServerError, "Failed to list inbox")
 		return
@@ -229,7 +229,7 @@ func MeGetInbox(w http.ResponseWriter, r *http.Request) {
 		ptrs[i] = &mails[i]
 	}
 	fillAttachments(r, ptrs...)
-	total, _ := repo.CountUnread(r.Context(), user.Username)
+	total, _ := repo.CountUnread(r.Context(), user.Username, "")
 
 	JSON(w, http.StatusOK, map[string]interface{}{
 		"mails": emptySlice(mails),

server/internal/handler/permission.go

@@ -394,6 +394,17 @@ func DecidePermission(w http.ResponseWriter, r *http.Request) {
 		// 那条路径要靠这个字段找到原会话，否则会凭空另开一个。
 		"session_id": perm.SessionID.String(),
 	}
+	/*
+		★ workspace：插件用它去收窄"等人期间新到的邮件"（那是一次 /mail/inbox 读，
+		而收件箱接口要求 workspace，缺了 400）。
+
+		为什么服务端给而不是让插件推：插件重启后待决映射丢光（上面那段说的），
+		此时它手上只有这个事件 —— 从事件里推不出工作区。而服务端**知道**
+		（`perm.SessionID` → `sessions.workspace`），一处给对，三平台都能用。
+	*/
+	if ws := repo.SessionWorkspaceOf(r.Context(), perm.SessionID); ws != "" {
+		payload["workspace"] = ws
+	}
 	if key, kind := repo.RelayKeyForMail(r.Context(), mailID); key != "" {
 		payload["relay_key"] = key
 		payload["relay_kind"] = kind