test(suite): 自检 3（判据不得埋在 process.exit 之后）+ TMPDIR 固化 + API 同名不同义表

## 自检 3（pi 提议）

自检 1/2 管"文件没接线"，管不到"检查写在 `process.exit()` 之后"—— 而那正是实际发生的
第 4 例（4 条玻璃判据被并发写入落到文件末尾）。成因是**结构性**的（并发写入总是往文件末尾
追加），所以它一定会再发生，而它下一次仍然不报错。静态扫一遍即可：`process.exit(` 之后
若再出现 `check(`，直接判红并指出文件。变异验证：往 `theme.test.mjs` 尾部追加一条 check → 判红。

## TMPDIR 固化（pi 建议，采纳）

"记得加 TMPDIR"这种约定活不过两次踩坑（hvigor、fpm 各一次）。所以不再靠口径：
- `npm run build:linux` 自带 `mkdir -p .tmp && TMPDIR=${TMPDIR:-$PWD/.tmp}`；
- `BUILD.md` 的 deb 一节写明这条前置与原因（`/tmp` 是 tmpfs、占内存、常年近满）。

## `docs/API.md`：`total` 不是总封数 + 同名不同义表

`GET /me/mail/inbox` 的 `total` 是**未读总数**（`repo.CountUnread`），不是本页/全部邮件数 ——
鸿蒙端曾因此写出「共 7 封」和「未读 7」两行自相矛盾的字。在人类接口开头加了醒目提示，
并新增一张表：`total`（未读数）/ `status`（邮件=unread|read，会话=active|archived）/
`status` 与 `is_read` 同义不同名。

## 验证

`npm test` 退出码 0：9 个判据文件全绿 + vitest 258/258（安装包已按判据要求重打，
AppImage 与 deb 均为最新）。

docs/API.md

@@ -64,6 +64,23 @@ curl {host}/api/v1/me/mail/inbox -H "Authorization: Bearer $TOKEN"
 
 ## 三、人类接口
 
+> **先读这一条：`total` 不是"总封数"。**
+> `GET /me/mail/inbox` 的响应是 `{"mails": [...], "total": N}`，而那个 `N` 是
+> **未读总数**（服务端 `repo.CountUnread`，与 `?status=` 过滤无关），**不是**本页/全部邮件数。
+> 它叫 `total` 是历史命名所致。后果很具体：鸿蒙端底部曾写「共 N 封」，
+> 于是同一屏上出现「共 7 封」和「未读 7」两行自相矛盾的字
+> （2026-09-14 修；WebUI 侧不读这个字段，故未受影响）。
+> 客户端**没有任何可信的"总封数"**可用 —— 想要"还有更多吗"只能看这一页是否取满
+> （`mails.length === limit`），不能把 `limit` 封说成全部。
+
+### 同名不同义 / 同义不同名（改代码前先看这张表）
+
+| 名字 | 在一处的意思 | 在另一处的意思 |
+|---|---|---|
+| `total` | `/me/mail/inbox`：**未读总数** | 别处（如 `/me/mail/sent` 等）才是"条数"，同名不同义，别看名字取值 |
+| `status` | 邮件上：`unread` / `read` | 会话上：`active` / `archived`（两套取值域，共用字段名） |
+| `status` + `is_read` | 邮件上这两个字段说的是同一件事（同义不同名） | 判断已读时别只看一个，旧数据可能只有一个被写对 |
+
 ### 邮件
 
 ```