fix(webui): re-read the account after a source switch, and stop the key card contradicting itself (P20, UAT4-1/4-2)

Author: fengzhi09

docs/webui.md

@@ -1375,7 +1375,7 @@ snapshot is broadcast to every SSE subscriber.
 | Row | Field | Missing-value sentence |
 | --- | --- | --- |
 | 账户名 | `identity.name`, trimmed | the engine answered and reported no name |
-| 当前套餐 | `tokenPlan.tier`, through the Token Plan card's own `planNameOf` | 「未订阅套餐」 when the engine reported no plan; the unread sentence when the surface itself failed |
+| 当前套餐 | `tokenPlan.tier`, through the Token Plan card's own `planNameOf` | 「未订阅套餐」 when the engine reported no plan; 「正在读取当前套餐…」 while a read is in flight; the unread sentence when the surface itself failed |
 | 配额概况 | `tokenPlanQuotaState`, plus `quota.fiveHour` / `quota.weekly` `remainingPercent` | 「引擎未返回读数」 per window; 「不限量」 when the engine reports the window unmetered |
 | 账户状态 | `status` | the unread sentence; a status token with no dictionary entry resolves to no sentence rather than leaking a raw enum |
 
@@ -1683,11 +1683,23 @@ return a mask while the engine rejects a mask submitted as a key.
 the `minimax_api` provider and the response says so (`tested:
 "stored_key"`). Two limits are the engine's contract, not this UI's:
 `testUserModel` takes no key override, so an unsaved value cannot be
-probed — the button is disabled with a title saying so while the field
-holds one — and the managed Token Plan credential is not a model-service
-key, so the Token Plan source has nothing to probe here. A probe that
-ran and failed is a completed probe, not an error: it renders the
-engine's status.
+probed — the button is disabled while the field holds one, and a visible
+line under the field says why, because the reason used to live only in a
+`title` attribute that keyboard and touch users never see — and the
+managed Token Plan credential is not a model-service key, so the Token
+Plan source has nothing to probe here. A probe that ran and failed is a
+completed probe, not an error: it renders the engine's status.
+
+**The key row is four states, not two.** The badge reads the engine's
+masked projection, but it is describing a field the user can be editing
+right now, so a typed-but-unsaved key is its own state (「已输入，未保存」)
+that outranks both 「已保存密钥」 and 「未启用」 — the user is replacing the
+stored key, or has plainly typed one, and neither badge is true. Symmetric
+to that, the engine's `NO_API_KEY` refusal is a verdict on an EMPTY field:
+typing one falsifies it, so the pinned 「请先填写 API Key」 is dropped on
+the next keystroke. A refusal that is not about the missing key — a
+transport failure, a rejected write — is still true afterwards and stays
+on screen.
 
 **Cost.** One extra read per settings-tab open. The read boots the
 engine runtime if none is up, which is the write-side contract and is
@@ -1702,6 +1714,50 @@ engine method behind it. The Token Plan cards stay on decision A1
 (本地版不适用) — wiring them to `/api/usage` and `/api/account` is a
 separate, undecided item, not a side effect of this one.
 
+### Usage & models: a source switch re-reads the account (P20)
+
+**The defect this fixes.** A UAT round trip on 2026-10-03 (板块 4) switched
+Token Plan → MiniMax API → Token Plan with a key stored in between. The
+Token Plan card came back reading 「未订阅套餐」 while `GET /api/account`
+answered `tier: "Ultra"` throughout, and only F5 recovered it. The
+endpoint was never wrong.
+
+**Root cause.** The plan name is read in `UsageModelsSection`
+(`webapp/components/panels.tsx`), mounted only while the port's view is on
+the token-plan tab, so a switch away and back remounts it. The read was
+`useEffect(..., [])` — once per mount — and that mount raced the engine:
+the section rendered in the same tick as `PUT /api/model-source`, and
+`GET /api/account` answers an engine that is still rebinding with HTTP
+**200** and `{ok: false, reason: "no_client"}`. The card read that as "no
+plan", nothing re-read it, and the section's state outlived the failure.
+
+**The re-read.** The port owns an `accountRevision` counter and increments
+it after every *successful* source write — the dropdown's `PUT
+/api/model-source` and 保存并使用's `PUT /api/model-source/api-key`, which
+switches the source inside the same engine transaction. The section's
+`/api/account` effect lists that counter as a dependency, so a confirmed
+write re-runs the read against an engine that has finished rebinding. A
+refused write bumps nothing: nothing changed, and a re-read would only
+spend a request to re-render the same answer.
+
+**A failed read may not un-know a name.** Revalidation alone is not enough,
+because the re-read can also lose the race. `reconciledAccount`
+(`webapp/components/usage-models-cards.tsx`, pure and unit-tested) keeps
+the last `ok: true` answer standing: only an `ok: true` payload is new
+information, so an unreachable account surface cannot knock a known plan
+off the card. An `ok: true` answer that reports no plan *does* replace it —
+the engine saying "no plan" is an answer, saying "unreachable" is not.
+
+**A read in flight is its own sentence.** With the name held, the only
+remaining nameless state is "not read yet", and it renders 「正在读取当前
+套餐…」 rather than 「未订阅套餐」. An account surface that has not
+answered has not said the user has no plan — that conflation was the
+visible half of UAT4-1.
+
+**Cost.** One `GET /api/account` per confirmed source write, on a surface
+the user has just acted on. The read is not debounced: a source switch is
+a deliberate act, not a stream of them.
+
 ### Follow-up messages: the switch is a behaviour (SB-4)
 
 **What the user sees.** 跟进消息行为 has three positions. While a task is

docs/webui.zh-CN.md

@@ -1130,20 +1130,36 @@ Token Plan 视图是桌面的五区块（页签 + 四卡）：
 
 **密钥行。** 已存的密钥显示为引擎的掩码，绝不显示明文；输入新值即在保存时替换。「保存并使用」是一次请求而不是两次：引擎在一个事务里既写密钥又切来源，因此界面不会出现"密钥已存、来源没切"的中间态。提交空值即**保留**哨兵（`changed: false`，不调用任何引擎写）——与 `PUT /api/providers` 同一约定；它存在的原因是读接口只能返回掩码，而引擎拒绝把掩码当密钥提交。
 
-**检测测的是什么、不测什么。** 检测针对 `minimax_api` 供应商上的**已存密钥**，并在响应里说明这一点（`tested: "stored_key"`）。两条限制来自引擎契约而非本界面：`testUserModel` 不接受密钥覆写，因此未保存的值无法被检测（输入框里有未保存内容时按钮禁用并给出原因），而托管的 Token Plan 凭据不是模型服务的密钥，Token Plan 来源在这里没有可检测对象。跑完但失败的检测是一次"跑完的检测"而不是错误，它渲染引擎给出的状态。
+**检测测的是什么、不测什么。** 检测针对 `minimax_api` 供应商上的**已存密钥**，并在响应里说明这一点（`tested: "stored_key"`）。两条限制来自引擎契约而非本界面：`testUserModel` 不接受密钥覆写，因此未保存的值无法被检测——输入框里有未保存内容时按钮禁用，且输入框下方常驻一行**可见**说明（该理由原本只写在 `title` 属性里，键盘与触屏用户根本看不到），而托管的 Token Plan 凭据不是模型服务的密钥，Token Plan 来源在这里没有可检测对象。跑完但失败的检测是一次"跑完的检测"而不是错误，它渲染引擎给出的状态。
+
+**密钥行是四态，不是两态。** 徽标读的是引擎的掩码投影，可它描述的是一个用户此刻可能正在编辑的输入框，因此"已填未存"是它自己的一态（「已输入，未保存」），优先级高于「已保存密钥」与「未启用」——用户要么正在替换已存密钥，要么明摆着填了内容，两个徽标此时都不成立。与之对称，引擎的 `NO_API_KEY` 拒绝是针对**空**输入框的判决：打一个字就把它证伪，因此那句钉住的「请先填写 API Key」在下一个字符处消失。与缺密钥无关的拒绝（传输失败、写入被驳回）此后依然成立，继续留在屏幕上。
 
 **代价。** 每次打开该设置页多一次读；这次读在没有运行时时会启动引擎，属于写侧契约，在这里可以接受（是用户打开了页签）。若将来把这次读取挪到页面级，必须改用不启动运行时的宿主 getter（见 `server/engine/model-source.js` KNOWN DEBT 2）。
 
 **本批没有做的事。** 添加模型弹窗的「自动获取」仍走内置 preset 目录（v2 没有按任意密钥查询供应商目录的方法）；Token Plan 四张卡维持 A1 决策的「本地版不适用」——把它们接到 `/api/usage` 与 `/api/account` 是另一个尚未拍板的独立项，不是本批的副作用。
 
+**切源后重拉账户（UAT4-1）**
+
+**缺陷。** 2026-10-03 的 UAT 第四板块（板块 4）做了一次三来源往返：Token Plan → MiniMax API（存了 Key）→ Token Plan。回来后 Token Plan 卡显示「未订阅套餐」，而 `GET /api/account` 全程答 `tier: "Ultra"`，只有 F5 能恢复。接口自始至终没有说谎。
+
+**根因。** 套餐名在 `UsageModelsSection`（`webapp/components/panels.tsx`）里读，而该组件只在端口视图停在 token-plan 页签时挂载，所以切走再切回会重新挂载。那次读是 `useEffect(..., [])`——每个挂载只读一次——而这次挂载与引擎赛跑：组件与 `PUT /api/model-source` 在同一 tick 渲染，此刻仍在重绑定的引擎会让 `GET /api/account` 以 HTTP **200** 加 `{ok: false, reason: "no_client"}` 应答。卡片把它读成"没有套餐"，此后无人重读，组件状态比失败活得更久。
+
+**重拉机制。** 端口持有一个 `accountRevision` 计数器，在**每一次成功的来源写入之后**递增——下拉的 `PUT /api/model-source`，以及「保存并使用」的 `PUT /api/model-source/api-key`（它在同一个引擎事务里切来源）。`UsageModelsSection` 的 `/api/account` effect 把该计数器列入依赖，于是被确认的写入会对已完成重绑定的引擎重跑这次读。被拒绝的写入不递增：什么都没变，重读只会白花一次请求去渲染同一个答案。
+
+**失败的读不能"忘掉"已知的名字。** 只做重拉还不够，因为重拉自己也会输掉赛跑。`reconciledAccount`（`webapp/components/usage-models-cards.tsx`，纯函数、有单测）会让上一个 `ok: true` 的答案继续站住：只有 `ok: true` 的载荷才算新信息，因此账户面不可达无法把已知套餐名从卡上打掉。而 `ok: true` 且明确报"没有套餐"的答案**会**替换它——引擎说"没有套餐"是回答，说"读不到"不是。
+
+**读取在途是它自己的一句话。** 名字被保住之后，唯一剩下的无名状态就是"还没读到"，它渲染「正在读取当前套餐…」而不是「未订阅套餐」。账户面没应答不等于用户没订阅——把两者混成一句正是 UAT4-1 的可见那一半。
+
+**代价。** 每一次被确认的来源写入多一次 `GET /api/account`，发生在用户刚刚操作过的界面上。不做防抖：切源是一次明确动作，不是一串动作。
+
 **账户分区（SB-5）**
 
 整个分区在挂载时读一次 `GET /api/account`。端点既不新建也不重复：它就是用户菜单账户卡已在读的同一份投影，按需读取的原因也相同——状态快照会广播给每一个 SSE 订阅者，账户数据不进去。
 
 | 行 | 字段 | 缺失时的文案 |
 | --- | --- | --- |
 | 账户名 | `identity.name`（去空白） | 引擎应答了但没给名字 |
-| 当前套餐 | `tokenPlan.tier`，走 Token Plan 卡自己的 `planNameOf` | 引擎没报套餐时是「未订阅套餐」；账户面本身不可达时是未读到的那句 |
+| 当前套餐 | `tokenPlan.tier`，走 Token Plan 卡自己的 `planNameOf` | 引擎没报套餐时是「未订阅套餐」；读取在途时是「正在读取当前套餐…」；账户面本身不可达时是未读到的那句 |
 | 配额概况 | `tokenPlanQuotaState`，以及 `quota.fiveHour` / `quota.weekly` 的 `remainingPercent` | 每个窗口各自显示「引擎未返回读数」；窗口被判为不限量时显示「不限量」 |
 | 账户状态 | `status` | 未读到的那句；字典里没有句子的状态枚举归为空，而不是把原始枚举漏给用户 |
 

packages/webui/webapp/components/panels.tsx

@@ -61,6 +61,7 @@ import {
   PlanCard,
   UsageBar,
   planNameOf,
+  reconciledAccount,
   resetCaption,
 } from "./usage-models-cards";
 
@@ -3416,6 +3417,7 @@ export function UsageModelsSection({
   autoAddProvider,
   onAutoAddConsumed,
   headless = false,
+  accountRevision = 0,
 }: {
   t: (key: MessageKey) => string;
   autoAddProvider?: boolean;
@@ -3425,6 +3427,10 @@ export function UsageModelsSection({
    * three-source switch instead and mounts this headless as its
    * token-plan landing; the header stays for any standalone use. */
   headless?: boolean;
+  /** P20 (UAT4-1): bumped by the port after every SUCCESSFUL model-source
+   * write, which re-runs the `/api/account` read. A remount alone is not
+   * a re-read worth trusting — the remount races the engine's rebind. */
+  accountRevision?: number;
 }) {
   // The reference opens on the Token Plan view. The one deliberate
   // exception is the add-provider deep-link: `autoAddProvider` fires the
@@ -3435,26 +3441,41 @@ export function UsageModelsSection({
   );
 
   // SB-7 (the A1 revision): the plan NAME is a real figure — /api/account's
-  // `tokenPlan.tier`. Read once on mount, the same way the user menu's account
-  // card reads it: the route returns the engine's projection and a failed or
-  // plan-less answer resolves to null, which the card renders as its honest
-  // 「未订阅套餐」 line. A rejected request is likewise a missing name, never a
+  // `tokenPlan.tier`. Read on mount, the same way the user menu's account
+  // card reads it. A rejected request is likewise a missing name, never a
   // default tier.
+  //
+  // P20 (UAT4-1): read-once was not enough. Switching the model source
+  // remounts this section — the port renders it only for the token-plan
+  // tab — so the read fired in the same tick as `PUT /api/model-source`
+  // and raced the engine re-binding to the new source. The losing read
+  // resolved to `{ok:false}` (HTTP 200, account unreachable), the card
+  // printed 「未订阅套餐」, and nothing re-read it until F5. The container
+  // therefore bumps `accountRevision` on every successful source write
+  // and this read re-runs. `reconciledAccount` keeps the last known-good
+  // answer when a revalidation read cannot beat the previous one, so a
+  // transient failure can no longer knock the name off the card.
   const [account, setAccount] = useState<api.AccountPayload | null>(null);
+  const [accountPending, setAccountPending] = useState(true);
   useEffect(() => {
     let live = true;
+    setAccountPending(true);
     void api
       .getAccount()
       .then((payload) => {
-        if (live) setAccount(payload);
+        if (!live) return;
+        setAccount((previous) => reconciledAccount(previous, payload));
       })
       .catch(() => {
-        // Unreachable account surface — the placeholder stands in for it.
+        // Unreachable account surface — the last known answer stands.
+      })
+      .finally(() => {
+        if (live) setAccountPending(false);
       });
     return () => {
       live = false;
     };
-  }, []);
+  }, [accountRevision]);
   const planName = planNameOf(account);
 
   // The reference's pill: the selected tab sits in a grey rounded pill,
@@ -3514,7 +3535,7 @@ export function UsageModelsSection({
       {view === "tokenPlan" ? (
         <>
           <SectionCard>
-            <PlanCard t={t} planName={planName} />
+            <PlanCard t={t} planName={planName} planPending={accountPending} />
           </SectionCard>
           <SectionCard>
             <UsageCard t={t} />