botmux 3.16.1 → 3.17.0

package/dist/dashboard/web/agent-workbench-panes.js

@@ -1,7 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { useCallback, useEffect, useMemo, useRef, useState, } from 'react';
+import { useCallback, useEffect, useMemo, useReducer, useRef, useState, } from 'react';
 import { clampSplitRatio, formatWorkbenchRelativeTime, paneTreeForLayout, workbenchExternalTerminalHref, workbenchPreviewHref, workbenchSessionTitle, workbenchTerminalHref, } from './agent-workbench-model.js';
-import { WorkbenchApiError, } from './agent-workbench-api.js';
+import { WorkbenchApiError, newTerminalAcquisitionId, } from './agent-workbench-api.js';
+// 控制权只有一份状态机（面板侧 + 外层意图），见该文件头部的注释。
+import { WORKBENCH_TERM_WRITE_MESSAGE, claimTerminalWrite, hasLiveTerminalWriteClaim, initialTerminalControlModel, terminalControlBusy, terminalControlMode, terminalControlNeedsMask, terminalControlReducer, terminalControlSettled, } from './agent-workbench-terminal-control.js';
 // 触屏鉴权契约只有一份实现，终端面板和会话坞共用（P1-17）。
 import { useTerminalViewLink, useTouchEnvironment } from './agent-workbench-touch.js';
 import { postWorkbenchTermAppearance, workbenchTermCanvasStyle, workbenchTermContainerClass, } from './agent-workbench-appearance.js';
@@ -22,6 +24,52 @@ export function readTerminalFrameStatus(frame) {
         return 'unknown';
     }
 }
+/**
+ * 生产实现：只读终端页的 `wsHasWrite`——**已经建立的那条 WebSocket** 实际拿到什么
+ * 权限（worker 在握手完成时用一条带外控制帧告诉页面，页面落成这个全局）。
+ * `null` / 读不到 = 还没有结论，一律 `unknown`。
+ *
+ * 为什么不拿页面那次 HTTP GET 的 `hasToken` 兜底：两次是**各自独立**的鉴权。页面是
+ * HTTP 请求，iOS WebView 会带 Cookie；紧接着的 WebSocket 升级**不带** Cookie，前置
+ * 代理给平台所有者补 WRITE grant 这件事也就跟着落空。拿 hasToken 兜底等于在 WS 还
+ * 没连上（或永远连不上）时宣称「可以输入」，用户打的字被 worker 原地丢掉，屏幕上
+ * 什么都不发生。没有依据时说未知，是这里唯一诚实的答案。
+ */
+export function readTerminalFrameWrite(frame) {
+    try {
+        const view = frame?.contentWindow;
+        const settled = view?.wsHasWrite;
+        if (settled === true)
+            return 'writable';
+        if (settled === false)
+            return 'readonly';
+        return 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * 终端页 → 工作台的一次写权限回报（终端页在 WS 建立后 postMessage 上抛）。
+ *
+ * 同源读全局已经够用，这条消息解决的是**时机**：不用等下一拍轮询，连上那一刻面板
+ * 就能把文案改对；而且万一将来这块 iframe 走到跨文档隔离的场景，同源读会直接抛，
+ * 消息通道仍然成立。来源校验沿用外观桥那一套：只认这块 iframe 自己的 contentWindow
+ * 发来的、结构完全对得上的消息。
+ *
+ * `write: null` 是终端页每次**重连**时先发的一条「退回未知」——上一条连接的结论套
+ * 不到新连接上。返回 `null` 表示「这压根不是我们的消息」，两者不能混。
+ */
+export function readTerminalWriteReport(data) {
+    if (!data || typeof data !== 'object')
+        return null;
+    const message = data;
+    if (message.type !== WORKBENCH_TERM_WRITE_MESSAGE)
+        return null;
+    if (message.write === null)
+        return 'unknown';
+    return typeof message.write === 'boolean' ? (message.write ? 'writable' : 'readonly') : null;
+}
 const FRAME_STATUS_POLL_MS = 1_000;
 /** 连续 8 拍（≈8 秒）都是 disconnected 才提示。终端页自己每 2 秒重连一次，正常网络下
  *  一两拍就连上了；8 秒还连不上，基本可以断定是这个浏览器环境拦掉了 ws://。 */
@@ -68,6 +116,74 @@ function useTerminalFrameWatch(params) {
     const onFrameLoad = useCallback(() => setLoadedFrameKey(frameKey), [frameKey]);
     return { blocked: enabled && blocked, onFrameLoad: enabled ? onFrameLoad : undefined };
 }
+/** 最多读几拍就收手：`hasToken` 是终端页顶部同步赋的全局，onLoad 时通常已经在了；
+ *  读不到基本就是读不到（跨域 / 页面报错），一直转下去没有意义。 */
+const FRAME_WRITE_MAX_TICKS = 5;
+/** 盯着 iframe 自报的写权限。只在需要它当判据的场景启用（触屏那条 viewToken
+ *  通道）；桌面同源链路的权威是控制权接口本身，多一个来源只会打架。 */
+function useTerminalFrameWrite(params) {
+    const { enabled, frameKey } = params;
+    const [write, setWrite] = useState('unknown');
+    const readRef = useRef(params.read);
+    useEffect(() => { readRef.current = params.read; });
+    useEffect(() => {
+        if (!enabled)
+            return undefined;
+        setWrite('unknown');
+        let ticks = 0;
+        const sample = () => {
+            const value = readRef.current();
+            if (value === 'unknown')
+                return false;
+            setWrite(value);
+            return true;
+        };
+        if (sample())
+            return undefined;
+        const timer = setInterval(() => {
+            ticks += 1;
+            if (sample() || ticks >= FRAME_WRITE_MAX_TICKS)
+                clearInterval(timer);
+        }, FRAME_STATUS_POLL_MS);
+        return () => clearInterval(timer);
+    }, [enabled, frameKey]);
+    return enabled ? write : 'unknown';
+}
+/**
+ * 收终端页在 WS 建立后主动上抛的写权限，并附带「这条上抛通道到底通没通」(`live`)。
+ *
+ * 只认这块 iframe 自己的 `contentWindow` 发来的消息（与外观桥同一套来源校验）：这
+ * 页面会被跨 origin 嵌入，别的窗口发来的同名消息一律不作数。换一块 iframe 就把结论
+ * 与 `live` 一起清空——上一块的判定套不到新的连接上。
+ *
+ * `live` 一旦为真，就说明 postMessage 通道有效、终端页的回报是这条 frame 的**权威**：
+ * 此后哪怕它回报 `unknown`（重连时先发的 `write:null`），父页也一律以它为准，绝不再
+ * 回退到轮询那份可能已经过期的 writable（见下方合并处注释）。首帧确认前、或页面根本
+ * 没上抛（取不到父页 origin 时它会放弃 postMessage），`live` 为假，此时才交给轮询兜底。
+ */
+function useTerminalFrameWriteReport(params) {
+    const { enabled, frameKey } = params;
+    const [state, setState] = useState({ write: 'unknown', live: false });
+    const frameRef = useRef(params.frame);
+    useEffect(() => { frameRef.current = params.frame; });
+    useEffect(() => {
+        setState({ write: 'unknown', live: false });
+        if (!enabled || typeof window === 'undefined' || !window.addEventListener)
+            return undefined;
+        const onMessage = (event) => {
+            const source = frameRef.current()?.contentWindow;
+            if (!source || event.source !== source)
+                return;
+            const reported = readTerminalWriteReport(event.data);
+            if (reported === null)
+                return;
+            setState({ write: reported, live: true });
+        };
+        window.addEventListener('message', onMessage);
+        return () => window.removeEventListener('message', onMessage);
+    }, [enabled, frameKey]);
+    return enabled ? state : { write: 'unknown', live: false };
+}
 function browserHref() {
     try {
         return typeof window === 'undefined' ? undefined : window.location?.href;
@@ -85,18 +201,89 @@ function apiErrorText(error) {
             terminal_unavailable: '终端不可用',
             control_busy: '另一个浏览器正在控制该终端',
             preview_not_registered: '未注册网页预览',
+            control_request_timeout: '控制权请求超时',
         };
         return known[error.code] ?? error.code.replaceAll('_', ' ');
     }
     return error instanceof Error ? error.message : String(error);
 }
+/**
+ * 写请求（takeover / release）的硬超时。
+ *
+ * 没有它时，一个**永远不回执**的 POST 会把这块面板整个焊死：`pending` 一直挂着 →
+ * `busy` 恒为真 → 标题栏和行内按钮永久禁用；轮询读数一律被在途写丢弃，界面停在
+ * 「正在接管输入…」；连卸载补偿也等不到那个 promise。半开连接、被代理吞掉的回执
+ * 都是这个形状，而且它不会自己好。
+ *
+ * 到点就按失败处理：进 `unknown`（**不是**只读——服务端很可能已经受理了）、遮罩
+ * 挡住盲输入、立刻发一次权威复核 GET 把状态收敛回来。
+ */
+export const TERMINAL_WRITE_TIMEOUT_MS = 10_000;
+/**
+ * 跑一次写请求，超时就自己判负。
+ *
+ * 两件事一起做，缺一不可：
+ *   ① `abort()` 掐掉请求本身——不然这条 fetch 会带着一个没人看的写租约继续飞；
+ *   ② 竞速 reject——调用方拿到的必须是一个**会结束**的 promise。只靠 abort 不够：
+ *      注入的 api 替身（以及某些不认 signal 的 fetch polyfill）可能压根不理会
+ *      signal，那样 promise 依旧永久 pending，超时也就形同虚设。
+ */
+async function withWriteTimeout(run, timeoutMs = TERMINAL_WRITE_TIMEOUT_MS) {
+    const controller = new AbortController();
+    let timer;
+    const expiry = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            try {
+                controller.abort();
+            }
+            catch { /* 环境不支持 abort：超时判定照旧成立 */ }
+            reject(new WorkbenchApiError(504, 'control_request_timeout'));
+        }, timeoutMs);
+    });
+    // 被丢下的那一半 promise 若稍后 reject，没人接就会冒成 unhandled rejection。
+    expiry.catch(() => { });
+    try {
+        return await Promise.race([run(controller.signal), expiry]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+/**
+ * 控制权未知时顶替终端 iframe 的那一屏。
+ *
+ * 它**不是**盖在 iframe 上的一层提示，而是把 iframe 整个换掉：真实 Chromium 里量
+ * 过——焦点已经落在 iframe 内部时，父文档往上盖一个 `position:absolute` 的层只吃
+ * 得到指针事件，`keyboard.type` 照旧一个字不落地打进终端。要真的挡住盲输入，只有
+ * 让那块可能可写的 iframe 从 DOM 里消失（焦点随之回到 document.body）。
+ *
+ * 自己再收一次焦点是兜底：将来若有调用方出于别的理由把 iframe 留着，至少焦点先
+ * 离开它；对读屏用户来说，这一屏也确实是此刻该被读出来的东西。
+ */
+function TerminalControlUnknown(props) {
+    const ref = useRef(null);
+    useEffect(() => {
+        try {
+            ref.current?.focus?.();
+        }
+        catch { /* 没有 DOM 的宿主（SSR / 组件测试） */ }
+    }, []);
+    return (_jsxs("div", { ref: ref, tabIndex: -1, className: "wb-pane-empty wb-control-unknown", role: "status", children: [_jsx("span", { "aria-hidden": "true", children: "\u25C7" }), _jsx("strong", { children: "\u63A7\u5236\u6743\u72B6\u6001\u672A\u77E5" }), _jsx("p", { children: "\u6CA1\u6709\u62FF\u5230\u786E\u8BA4\uFF0C\u8FD9\u5757\u7EC8\u7AEF\u53EF\u80FD\u4ECD\u7136\u53EF\u5199\u3002\u5DF2\u65AD\u5F00\u7EC8\u7AEF\u753B\u9762\u6321\u4F4F\u8F93\u5165\uFF0C\u6B63\u5728\u91CD\u65B0\u786E\u8BA4\u3002" }), _jsx("button", { type: "button", onClick: props.onRetry, children: "\u7ACB\u5373\u91CD\u8BD5" })] }));
+}
 export function TerminalPane(props) {
-    const [control, setControl] = useState(null);
-    const [phase, setPhase] = useState('loading');
-    const [error, setError] = useState('');
-    const [frameGeneration, setFrameGeneration] = useState(0);
-    const controlRef = useRef(null);
-    const requestGeneration = useRef(0);
+    // 控制权的唯一状态机。散着的 useState 版本让观察轮询和写操作共用一个
+    // generation，15 秒一发的轮询会把在途写的回执丢掉；失败又一律乐观压成只读。
+    const [model, dispatch] = useReducer(terminalControlReducer, undefined, initialTerminalControlModel);
+    /** 观察与写各自一份 epoch：写只被更新的写作废，轮询作废不了它。 */
+    const observeEpoch = useRef(0);
+    const writeEpoch = useRef(0);
+    /** 卸载后到达的写回执要走补偿路径，不能再 dispatch。 */
+    const mounted = useRef(true);
+    useEffect(() => {
+        mounted.current = true;
+        return () => { mounted.current = false; };
+    }, []);
     const terminalUrl = workbenchTerminalHref(props.session, props.location);
     const externalTerminalUrl = workbenchExternalTerminalHref(props.session);
     // 触屏和桌面在鉴权方式上彻底分道，详见下面那段注释。
@@ -128,108 +315,265 @@ export function TerminalPane(props) {
     const frameUrl = !externalTerminalUrl && touch
         ? viewLinkUrl
         : props.authenticated ? terminalUrl : viewLinkUrl;
-    const applyControl = useCallback((next, reloadOnDowngrade = true) => {
-        const previous = controlRef.current;
-        controlRef.current = next;
-        setControl(next);
-        if (reloadOnDowngrade
-            && previous?.mode === 'controlled' && previous.owned
-            && (next.mode !== 'controlled' || !next.owned)) {
-            setFrameGeneration(value => value + 1);
-        }
-    }, []);
-    const refresh = useCallback(async (source, signal) => {
-        const generation = ++requestGeneration.current;
+    const sessionId = props.session.sessionId;
+    /** 一次观察（首屏 / 15s 轮询 / 写失败后的复核）。回执带着自己的 epoch 回来，
+     *  过期的、或有写在途的，都在 reducer 里被丢掉。 */
+    const observe = useCallback(async (source, signal) => {
         // Without a Dashboard cookie the control API can only 401, and taking over
         // is not on offer anyway — settle into read-only instead of surfacing an
         // authentication error the viewer cannot act on.
         if (!terminalUrl || externalTerminalUrl || !props.authenticated) {
-            setPhase('ready');
-            applyControl({ mode: 'readonly', owned: false });
+            dispatch({ type: 'settle-readonly' });
             return;
         }
-        if (source === 'load')
-            setPhase('loading');
+        const epoch = ++observeEpoch.current;
+        dispatch({ type: 'observe-start', epoch, source });
         try {
-            const next = await props.api.getTerminalControl(props.session.sessionId, signal);
-            if (generation !== requestGeneration.current)
-                return;
-            applyControl(next);
-            setError('');
-            setPhase('ready');
+            const next = await props.api.getTerminalControl(sessionId, signal);
+            dispatch({ type: 'observe-settled', epoch, control: next });
         }
         catch (cause) {
-            if (signal?.aborted || generation !== requestGeneration.current)
+            if (signal?.aborted)
                 return;
-            applyControl({ mode: 'readonly', owned: false });
-            setError(apiErrorText(cause));
-            setPhase('error');
+            dispatch({
+                type: 'observe-failed',
+                epoch,
+                error: apiErrorText(cause),
+                // 触屏走的是 viewToken 只读通道，没有租约可言；无 canControl 的身份连
+                // takeover 都会 403。这两类读失败落只读才是事实。
+                canHoldLease: props.capabilities.canControl && !touch,
+            });
         }
-    }, [applyControl, externalTerminalUrl, props.api, props.authenticated, props.session.sessionId, terminalUrl]);
+    }, [externalTerminalUrl, props.api, props.authenticated, props.capabilities.canControl, sessionId, terminalUrl, touch]);
     useEffect(() => {
         const controller = new AbortController();
-        void refresh('load', controller.signal);
-        const timer = setInterval(() => { void refresh('poll', controller.signal); }, 15_000);
+        void observe('load', controller.signal);
+        const timer = setInterval(() => { void observe('poll', controller.signal); }, 15_000);
         return () => {
-            requestGeneration.current += 1;
+            // 换会话 / 卸载：作废在途观察。写不走这个计数器——它有自己的 epoch，
+            // 卸载后的写回执要留到补偿逻辑里处理，不能在这里"顺手"丢掉。
+            observeEpoch.current += 1;
             clearInterval(timer);
             controller.abort();
         };
-    }, [refresh]);
+    }, [observe]);
+    const leaseExpiresAt = model.authoritative?.expiresAt;
     useEffect(() => {
-        if (control?.mode !== 'controlled' || !control.owned || !control.expiresAt)
+        if (model.phase !== 'controlled' || !leaseExpiresAt)
             return undefined;
-        const timer = setTimeout(() => { void refresh('poll'); }, Math.max(0, control.expiresAt - Date.now()) + 25);
+        const timer = setTimeout(() => { void observe('poll'); }, Math.max(0, leaseExpiresAt - Date.now()) + 25);
         return () => clearTimeout(timer);
-    }, [control?.expiresAt, control?.mode, control?.owned, refresh]);
-    // Fires once per session for the "open writable" shortcut. A platform owner
-    // (`fixed`) already writes, and an unauthenticated viewer cannot take over at
-    // all, so neither needs the request. 触屏也跳过：那边的 iframe 走 viewToken 只读通道，
-    // 抢来的写权限自己用不上，反而会把别人电脑上的输入权顶掉。canControl=false 的
-    // 身份（平台 teammate/guest 等）同样跳过——那个 POST 只会 403（P1-4）。
-    const autoTakeoverDone = useRef(null);
+    }, [leaseExpiresAt, model.phase, observe]);
+    // 写失败 → 立刻复核一次。P1-3：release 失败绝不能乐观宣称只读，真实的写租约
+    // 可能还在服务端挂着；这一发 GET 是把 unknown 收敛回权威读数的唯一途径
+    // （期间可写 iframe 由下面那层遮罩挡住）。
+    useEffect(() => {
+        if (model.reconcileNonce === 0)
+            return undefined;
+        const controller = new AbortController();
+        void observe('reconcile', controller.signal);
+        return () => controller.abort();
+    }, [model.reconcileNonce, observe]);
+    // 开场只读意图只兑现一次，在这块面板第一次拿到**权威**读数的时候：发现自己还
+    // 攥着上一轮留下的租约（标题栏接管过，行内点「终端」把它降回只读），就把它还
+    // 回去。这是「打开只读终端」名副其实的关键：不真的释放，只读就只是外层记了一笔，
+    // 面板照样可输入，用户点完「终端」看到的还是一个可写终端。
+    // 它必须是一次性的——兑现之后控制权只由标题栏的「接管输入 / 释放输入」驱动，
+    // 否则只读面板会把用户刚在标题栏按下的接管在同一拍里撤销回去。
+    // 平台所有者（`fixed`）恒可写、既接管不了也释放不了，直接跳过；未登录 / 触屏 /
+    // canControl=false（平台 teammate/guest 等）同样跳过——它们压根没有租约可还，
+    // 那个 POST 只会 401/403（P1-4），触屏那边更是走 viewToken 只读通道。
+    const openIntentApplied = useRef(null);
     useEffect(() => {
-        if (!props.autoTakeControl || !props.authenticated || !props.capabilities.canControl
-            || touch || phase !== 'ready')
+        if (props.autoTakeControl === undefined)
+            return;
+        if (!props.authenticated || !props.capabilities.canControl || touch)
             return;
-        if (!control || control.mode !== 'readonly' || control.fixed)
+        if (!terminalControlSettled(model))
             return;
-        if (autoTakeoverDone.current === props.session.sessionId)
+        const control = model.authoritative;
+        if (!control || control.fixed)
             return;
-        autoTakeoverDone.current = props.session.sessionId;
-        void mutate('takeover');
+        if (openIntentApplied.current === sessionId)
+            return;
+        openIntentApplied.current = sessionId;
+        if (control.mode === 'controlled' && control.owned)
+            void mutate('release');
     });
+    /**
+     * 这块面板**可能已经提交**的接管集合（第 16 点）。
+     *
+     * 为什么是集合而不是单值：单值每次 takeover 都覆盖上一次，于是「acq1 提交但回执
+     * 丢 → unknown → 用户立即重试 acq2、acq2 在到服务端之前就失败」时，客户端只剩
+     * acq2，服务端却仍持有 acq1；卸载补偿只 release(acq2)，acq1 一路泄漏到 TTL。改成
+     * 集合后，本 pane POST 过的每一次 acquisition 都留着，卸载时逐个按各自的 id 做 CAS
+     * （服务端最多匹配其中一条，其余全部落空即无害）。
+     *
+     * 键是 acquisition id：客户端在 POST **之前**自己生成，不依赖回执——回执可能根本
+     * 回不来，而那恰恰是最需要补偿的场景。手动释放成功 / 恒可写身份确认后清空整份
+     * 集合。每条都连着 sessionId：面板换会话是重挂，但卸载清理跑在 React 之外，必须
+     * 自带「这是哪个会话的哪一次」才不会还错。
+     */
+    const heldAcquisitions = useRef(new Map());
+    /** 快照并清空「可能已提交」集合，返回待补偿的全部条目。快照 + 清空同步完成，两条
+     *  在途补偿就不会各自拿到同一批条目重复发请求（CAS 本身幂等，这里只是少发无谓的）。 */
+    const drainHeldAcquisitions = () => {
+        const entries = [...heldAcquisitions.current.values()];
+        heldAcquisitions.current.clear();
+        return entries;
+    };
+    /**
+     * 收掉一批**没人管的**接管：逐个按各自的 acquisition 做条件释放。
+     *
+     * 每一条的两条判据缺一不可：
+     *   ① 这份文档里还有活面板攥着同一把租约 → 它不是孤儿，别动。租约挂在
+     *      （会话 × 登录）上，第二块面板 takeover 拿到的是同一把，服务端看来两次
+     *      请求完全同形，只有这里分得清（同标签页内的判据）。
+     *   ② 释放带上**那一次自己的** acquisition id，服务端按它 CAS。跨标签页 / 跨设备
+     *      的抢先接管只有服务端看得见，不匹配时它拒绝，用户正在打字的那块终端不受伤。
+     *
+     * 这里**不再**去 GET 一次「当前 marker」再拿它释放：事后读到的是此刻活着的那一次
+     * acquisition，跨标签页接管之后正是别人的那一把，拿它补偿等于精准误删。
+     * 幂等：租约已经没了就是 `released:false`，被别人接管过就是 `control_lease_superseded`，
+     * 服务端最多匹配集合里一条、其余全部落空即无害，所以随后 socket 断开再走一遍也不冲突。
+     */
+    const compensateAcquisitions = useCallback(async (targets) => {
+        for (const target of targets) {
+            if (hasLiveTerminalWriteClaim(target.sessionId))
+                continue;
+            await props.api
+                .releaseTerminal(target.sessionId, undefined, target.acquisitionId)
+                .catch(() => { });
+        }
+    }, [props.api]);
+    /** 在途写的计数。卸载补偿据此让路：在途那一条自己会在回执（或失败）之后补偿，
+     *  它比卸载那一刻知道得更多，两边都发只是多一次必然被拒的请求。 */
+    const writesInFlight = useRef(0);
     const mutate = async (action) => {
-        const generation = ++requestGeneration.current;
-        setPhase('busy');
+        const epoch = ++writeEpoch.current;
+        // POST **之前**就把这一次接管的 id 定下来，并记进「可能已提交」集合。回执丢了也
+        // 不影响补偿的精确度；单值覆盖会漏掉更早那次尚未收敛的接管（第 16 点）。
+        const acquisitionId = action === 'takeover' ? newTerminalAcquisitionId() : undefined;
+        if (acquisitionId)
+            heldAcquisitions.current.set(acquisitionId, { sessionId, acquisitionId });
+        writesInFlight.current += 1;
+        dispatch({ type: 'write-start', epoch, action });
         try {
-            const next = action === 'takeover'
-                ? await props.api.takeoverTerminal(props.session.sessionId)
-                : await props.api.releaseTerminal(props.session.sessionId);
-            if (generation !== requestGeneration.current)
+            // 硬超时：永久 pending 的 POST 会把 busy / 按钮 / 卸载补偿一起焊死。
+            const next = await withWriteTimeout(signal => (action === 'takeover'
+                ? props.api.takeoverTerminal(sessionId, signal, acquisitionId)
+                : props.api.releaseTerminal(sessionId, signal)));
+            // 手动释放成功（租约已还清）/ 恒可写身份（压根没有租约）→ 整份集合清空，卸载
+            // 时也就没什么要补偿。takeover 成功则保留——它是本 pane 此刻握着的那把活租约，
+            // 连同更早提交但回执丢失的几次一并留到卸载时逐个 CAS（服务端最多匹配一条）。
+            if (action === 'release' || next.fixed === true)
+                heldAcquisitions.current.clear();
+            if (!mounted.current) {
+                // 服务端刚刚把写租约发给了这次调用，面板却已经关掉 / 换会话 / 离开工作台：把
+                // 集合里每一次 acquisition 都逐个 CAS 释放（release 成功已清空 → 这里空转）。
+                void compensateAcquisitions(drainHeldAcquisitions());
                 return;
-            applyControl(next, false);
-            setError('');
-            setFrameGeneration(value => value + 1);
-            setPhase('ready');
+            }
+            dispatch({ type: 'write-settled', epoch, control: next });
         }
         catch (cause) {
-            if (generation !== requestGeneration.current)
+            if (!mounted.current) {
+                // 失败不代表服务端没受理——超时、断连都只是丢了回执。这里**不能**裸 return，
+                // 也不能去问「现在的租约是谁的」，只能认自己 POST 前生成的那些 id：把本 pane
+                // 全部「可能已提交」的 acquisition 逐个条件释放（含这次 attempt 与更早提交但
+                // 回执丢失的那几次），服务端最多匹配其中一条。
+                void compensateAcquisitions(drainHeldAcquisitions());
                 return;
-            applyControl({ mode: 'readonly', owned: false });
-            setError(apiErrorText(cause));
-            setPhase('error');
+            }
+            dispatch({ type: 'write-failed', epoch, error: apiErrorText(cause) });
+        }
+        finally {
+            writesInFlight.current -= 1;
         }
     };
+    // 恒可写身份没有租约可还（服务端会 403），别把它记成「握着接管」。
+    useEffect(() => {
+        if (model.authoritative?.fixed === true)
+            heldAcquisitions.current.clear();
+    }, [model.authoritative]);
+    /**
+     * 关面板 / 换会话 = 放弃本 pane 可能已提交的每一次接管（第 15 / 16 点）。
+     *
+     * 接管已经回执、model 也已经 controlled，但新的 iframe / WS 还没连上就把终端关掉
+     * 时：没有在途 promise 可补偿，也没有已注册的 socket 会在断开时触发服务端那条
+     * disconnect —— 旧实现只撤掉本地认领，租约一路挂到 TTL 到期，同一个会话在那之前
+     * 谁也接管不了。这里把「可能已提交」集合里的每一次 acquisition 都做一次条件释放，
+     * 与 socket 随后断开触发的清理天然可重入（服务端每一条都是同一把 CAS）。
+     *
+     * 走微任务是必需的：这块面板自己那份写租约认领由另一个 effect 的清理撤销，React
+     * 按 effect 定义顺序跑清理，同步做判断有可能看见的是**自己**的认领而白白放弃补偿。
+     * `compensateRef` 同理——把函数写进依赖会让 api 引用一变就"卸载"一次。
+     */
+    const compensateRef = useRef(compensateAcquisitions);
+    useEffect(() => { compensateRef.current = compensateAcquisitions; });
+    useEffect(() => () => {
+        // 有写在途时让路：那一条自己会在回执 / 失败之后补偿整份集合，而且那时它知道得更多。
+        if (writesInFlight.current > 0)
+            return;
+        const targets = [...heldAcquisitions.current.values()];
+        if (targets.length === 0)
+            return;
+        heldAcquisitions.current.clear();
+        void Promise.resolve().then(() => compensateRef.current(targets));
+    }, [sessionId]);
+    // 只要这块面板**可能**握着写租约，就在登记簿上留个名：别的面板的迟到补偿据此
+    // 知道「这把租约还有人在管」。卸载时 effect 的清理先跑，补偿的续行在其后的微
+    // 任务里，所以补偿看到的永远是**别人**的认领，不是自己的。
+    const writeClaim = useRef({});
+    useEffect(() => {
+        if (!model.mayWrite)
+            return undefined;
+        return claimTerminalWrite(sessionId, writeClaim.current);
+    }, [model.mayWrite, sessionId]);
     const frameRef = useRef(null);
-    const frameKey = `${props.session.sessionId}-${frameGeneration}`;
+    /**
+     * 链接换代计数。短时 viewToken 到期前会**换一条链接**，那是一条全新的连接、全新的
+     * 授权；不把它算进 iframe / watcher 的 key，React 就会复用同一块 iframe 与同一个
+     * WindowProxy，上一条连接回报的写权限一路留着，UI 继续说「可输入」。
+     * 存的是计数不是链接本身：key 会进 DOM，token 绝不能跟着进去。
+     */
+    const linkGeneration = useRef(0);
+    const lastFrameUrl = useRef(undefined);
+    if (lastFrameUrl.current !== frameUrl) {
+        if (lastFrameUrl.current !== undefined)
+            linkGeneration.current += 1;
+        lastFrameUrl.current = frameUrl;
+    }
+    const frameKey = `${sessionId}-${model.frameGeneration}-l${linkGeneration.current}`;
     const readFrameStatus = props.readFrameStatus ?? readTerminalFrameStatus;
     const frameWatch = useTerminalFrameWatch({
         enabled: touch,
-        sessionId: props.session.sessionId,
+        sessionId,
         frameKey,
         read: () => readFrameStatus(frameRef.current),
     });
+    // 触屏那条 viewToken 通道到底能不能写，只有终端页自己知道（前置代理会给平台
+    // owner 的 viewToken 请求补 WRITE grant，而补不补又取决于这个 WebView 带不带
+    // Cookie）。桌面不启用：那边的权威是控制权接口，多一个来源只会两边打架。
+    const readFrameWrite = props.readFrameWrite ?? readTerminalFrameWrite;
+    const polledFrameWrite = useTerminalFrameWrite({
+        enabled: touch,
+        frameKey,
+        read: () => readFrameWrite(frameRef.current),
+    });
+    // 终端页连上 WS 那一刻主动上抛的结论。它比轮询早、也比轮询确定（轮询读的是同一
+    // 份全局，只是要等下一拍），所以有它就以它为准。
+    const reportedFrameWrite = useTerminalFrameWriteReport({
+        enabled: touch,
+        frameKey,
+        frame: () => frameRef.current,
+    });
+    // 上抛通道一旦通过(`live`)，它就是这条 frame 的权威判据：哪怕它此刻回报 `unknown`
+    // （重连时终端页先发的 `write:null`），也一律以它为准，**绝不**回退到轮询那份可能已
+    // 经过期的 writable —— 本连接在自己的新首帧确认前一律「未知」（换链/重连都算未确认）。
+    // 只有上抛通道还没通（首帧前、或页面取不到父页 origin 放弃了 postMessage）才交给轮询
+    // 兜底；轮询本身也只认 wsHasWrite，读不到同样是「未知」，不会拿 HTTP hasToken 顶替。
+    const frameWrite = reportedFrameWrite.live ? reportedFrameWrite.write : polledFrameWrite;
     // 终端渲染风格：容器 class 管几何（行距 / 内边距），xterm 的配色住在跨文档的
     // 终端页里，父页换 class 它收不到 —— 必须把 theme 推过去，否则会出现「工作台
     // 换了配色、终端还是旧色」的半截状态。切换和重挂 iframe 时各推一次。
@@ -244,27 +588,91 @@ export function TerminalPane(props) {
         frameWatch.onFrameLoad?.();
         pushTermAppearance();
     }, [frameWatch, pushTermAppearance]);
-    // 触屏挂的是 viewToken 只读通道：控制权接口哪怕报「已接管」或平台所有者（fixed），这块
-    // iframe 也送不进输入，徽标必须跟着说只读，否则和下面那行反馈自相矛盾。
-    const controlled = !touch && control?.mode === 'controlled' && control.owned;
-    const status = controlled ? '可输入' : '只读';
+    const control = model.authoritative;
+    const busy = terminalControlBusy(model);
+    const fixed = control?.fixed === true;
+    // 标题栏能不能切模式 —— 也就是这块面板有没有第二种状态可去。触屏（viewToken
+    // 通道没有租约可接管）、无 canControl 能力、恒可写身份、外部终端都没有。
+    const canSwitchMode = !externalTerminalUrl && !!terminalUrl && props.authenticated
+        && props.capabilities.canControl && !touch && !fixed;
+    // 触屏这块 iframe 到底能不能写，最终以终端页自己的结论为准。它还没给出结论时
+    // 别急着猜：非恒可写身份走的 viewToken 通道**必定**只读（前置代理只对平台所有者
+    // 补 WRITE grant），照实说只读；恒可写身份则取决于这个 WebView 带不带 Cookie，
+    // 只能先说未知，等页面自己说话——这总好过写死一句与实际能力相反的「只读」。
+    const touchWrite = frameWrite !== 'unknown' ? frameWrite : fixed ? 'unknown' : 'readonly';
+    // 用户眼里的模式。触屏不看租约：那条通道上「控制权接口说什么」和「这一页能不能
+    // 输入」本来就是两件事，照抄接口就会得出「UI 说只读、链路其实可写」的分裂表述
+    // （P1-4）。
+    const paneMode = touch
+        ? (touchWrite === 'writable' ? 'controlled' : touchWrite === 'readonly' ? 'readonly' : 'unknown')
+        : terminalControlMode(model);
+    const controlled = paneMode === 'controlled';
+    // 徽标只说有依据的话。首屏 GET 还在飞时说「只读」是最容易被信以为真的一句假话：
+    // 同一个登录留下的写租约会让这块 iframe 真的可以打字（详见状态机文件里 loading
+    // 那条注释），所以 loading 有自己的说法，不借用只读。
+    const status = controlled ? '可输入'
+        : paneMode === 'unknown' ? '未知'
+            : paneMode === 'loading' ? '检查中' : '只读';
+    const chipClass = controlled ? 'is-controlled'
+        : paneMode === 'unknown' ? 'is-unknown'
+            : paneMode === 'loading' ? 'is-checking' : 'is-readonly';
+    const chipGlyph = controlled ? '◆'
+        : paneMode === 'unknown' ? '◇'
+            : paneMode === 'loading' ? '⋯' : '◌';
+    // 未知且这块 iframe 可能仍然可写 → 盖住它。这一刻既不能说「已接管」也不能说
+    // 「只读」，而盲输入会真的打进终端（P1-3）。复核 GET 回来后遮罩自动撤掉。
+    const masked = !touch && terminalControlNeedsMask(model);
+    /**
+     * 这条通道有没有可能握着写租约。租约挂在（会话 × 登录）上，**不**挂在面板上：
+     * 同一个登录里上一块面板接管过、这块面板刚挂上来时，服务端那把写租约仍在，前置
+     * 代理照旧会给这个 iframe 补 WRITE grant —— 也就是说它**真的能打字**。
+     * `canControl=false`（平台 teammate/guest）与无凭证的只读通道则永远握不到。
+     */
+    const leaseCapableChannel = !externalTerminalUrl && !!terminalUrl && !touch
+        && props.authenticated && props.capabilities.canControl;
+    /**
+     * 首屏 GET 还没回来（第 9 / 9b 点）：这一刻我们**什么都不知道**，而上面那条判据
+     * 说明它可能可写。iframe 一旦挂上去就能收键盘，等 GET 回来再撤已经晚了 —— 所以
+     * 能握租约的通道在 loading 期间干脆不挂。随后才会被识别为 fixed 的平台 owner 也
+     * 走这条：识别完成前它同样是 authenticated + canControl。
+     */
+    const withheldWhileChecking = model.phase === 'loading' && leaseCapableChannel;
+    const frameWithheld = masked || withheldWhileChecking;
+    // 把徽标看到的这份结论原样回执给外层。回执的是**渲染出来的模式**（含触屏那层
+    // 覆盖），不是接口原始读数——外层拿它决定行内按钮的开关语义，两边看到的必须是
+    // 同一个「用户眼里的模式」。sessionId 一并带上：面板换会话是重挂，回执路上不该
+    // 有把上一块面板的结论套到新会话头上的缝。
+    const onControlModeChange = props.onControlModeChange;
+    const toggleOnly = !canSwitchMode;
+    useEffect(() => {
+        onControlModeChange?.({ sessionId, mode: paneMode, fixed, toggleOnly, busy });
+    }, [busy, fixed, onControlModeChange, paneMode, sessionId, toggleOnly]);
     const expires = controlled && control?.expiresAt
         ? formatWorkbenchRelativeTime(control.expiresAt, props.now, 'zh-CN')
         : null;
     return (_jsxs("section", { className: `wb-pane wb-terminal-pane ${workbenchTermContainerClass(appearance.termStyle)}`, 
         // 外壳那圈安全边距的底色 = 这一刻真正渲染出来的 xterm 底色（同一个
         // workbenchTermTheme 也在往 iframe 里推），经典渲染下才不会露出一圈更黑的边。
-        style: workbenchTermCanvasStyle(appearance.termStyle, skin), "aria-label": "\u7EC8\u7AEF\u9762\u677F", children: [_jsxs("header", { className: "wb-pane-titlebar", children: [_jsxs("div", { className: "wb-pane-identity", children: [_jsx("span", { className: "wb-pane-glyph", "aria-hidden": "true", children: "\u203A_" }), _jsx("strong", { children: "\u7EC8\u7AEF" }), _jsxs("span", { className: `wb-mode-chip ${controlled ? 'is-controlled' : 'is-readonly'}`, children: [_jsx("span", { "aria-hidden": "true", children: controlled ? '◆' : '◌' }), status] }), expires ? _jsx("span", { className: "wb-lease-time", children: `${expires}到期` }) : null] }), _jsx(WorkbenchTermStyleSegment, { termStyle: appearance.termStyle }), _jsxs("div", { className: "wb-pane-actions", children: [frameUrl ? _jsx("a", { href: frameUrl, target: "_blank", rel: "noopener noreferrer", children: "\u65B0\u6807\u7B7E\u9875\u6253\u5F00" }) : null, !externalTerminalUrl && terminalUrl && props.authenticated
-                                && props.capabilities.canControl && !touch && !control?.fixed ? (controlled
-                                ? _jsx("button", { type: "button", disabled: phase === 'busy', onClick: () => void mutate('release'), children: "\u91CA\u653E\u8F93\u5165" })
-                                : _jsx("button", { type: "button", disabled: phase === 'busy', onClick: () => void mutate('takeover'), children: "\u63A5\u7BA1\u8F93\u5165" })) : null] })] }), _jsx("div", { className: "wb-pane-feedback", role: "status", "aria-live": "polite", children: touch ? '只读查看中。手机端为只读视图，需要输入请在电脑上操作。'
-                    : phase === 'loading' ? '正在检查终端权限…' : error || (control?.fixed
-                        ? '平台所有者身份已登录，可直接输入。'
-                        : controlled ? '已接管，可键盘输入。'
-                            // 没有接管能力的身份别劝人去点一个根本没渲染的按钮。
-                            : props.authenticated && props.capabilities.canControl ? '只读查看中，点「接管输入」可操作。'
-                                : props.authenticated ? '只读查看中，当前身份不可接管输入。'
-                                    : '只读查看。登录 Dashboard 后可接管。') }), _jsx("div", { className: "wb-pane-frame-shell", children: externalTerminalUrl ? (_jsxs("div", { className: "wb-pane-empty", children: [_jsx("span", { "aria-hidden": "true", children: "\u2197" }), _jsx("strong", { children: "\u5916\u90E8 Riff \u7EC8\u7AEF" }), _jsx("p", { children: "\u8BE5\u540E\u7AEF\u4E0D\u5728\u5DE5\u4F5C\u53F0\u9762\u677F\u5185\u5C55\u793A\u3002" }), _jsx("a", { href: externalTerminalUrl, target: "_blank", rel: "noopener noreferrer", children: "\u6253\u5F00\u5916\u90E8\u7EC8\u7AEF" })] })) : frameUrl ? (_jsxs(_Fragment, { children: [_jsx("iframe", { ref: frameRef, className: "wb-pane-frame", src: frameUrl, title: `终端 — ${workbenchSessionTitle(props.session)}`, allow: "clipboard-read; clipboard-write", referrerPolicy: "no-referrer", onLoad: onFrameLoad }, frameKey), frameWatch.blocked ? (_jsxs("div", { className: "wb-pane-empty wb-ws-blocked", role: "status", children: [_jsx("span", { "aria-hidden": "true", children: "\u26A0" }), _jsx("strong", { children: "\u7EC8\u7AEF\u5B9E\u65F6\u8FDE\u63A5\u672A\u5EFA\u7ACB" }), _jsx("p", { children: "\u5F53\u524D\u6D4F\u89C8\u5668\u73AF\u5883\u9650\u5236\u4E86\u975E\u52A0\u5BC6\u7684\u5B9E\u65F6\u8FDE\u63A5\uFF08iOS \u5185\u5E38\u89C1\uFF09\u3002\u53EF\u5C1D\u8BD5\u7528\u7CFB\u7EDF\u6D4F\u89C8\u5668\u6253\u5F00\uFF0C\u6216\u5728\u7535\u8111\u4E0A\u67E5\u770B\u3002" }), _jsx("a", { href: frameUrl, target: "_blank", rel: "noopener", children: "\u5728\u6D4F\u89C8\u5668\u4E2D\u6253\u5F00" }), _jsx("p", { children: "\u98DE\u4E66\u5185\u53EF\u901A\u8FC7\u53F3\u4E0A\u89D2 \u22EF \u83DC\u5355\u9009\u62E9\u300C\u5728\u6D4F\u89C8\u5668\u6253\u5F00\u300D\u3002" })] })) : null] })) : (touch || !props.authenticated) && !externalTerminalUrl && terminalUrl ? (
+        style: workbenchTermCanvasStyle(appearance.termStyle, skin), "aria-label": "\u7EC8\u7AEF\u9762\u677F", children: [_jsxs("header", { className: "wb-pane-titlebar", children: [_jsxs("div", { className: "wb-pane-identity", children: [_jsx("span", { className: "wb-pane-glyph", "aria-hidden": "true", children: "\u203A_" }), _jsx("strong", { children: "\u7EC8\u7AEF" }), _jsxs("span", { className: `wb-mode-chip ${chipClass}`, children: [_jsx("span", { "aria-hidden": "true", children: chipGlyph }), status] }), expires ? _jsx("span", { className: "wb-lease-time", children: `${expires}到期` }) : null] }), _jsx(WorkbenchTermStyleSegment, { termStyle: appearance.termStyle }), _jsxs("div", { className: "wb-pane-actions", children: [frameUrl ? _jsx("a", { href: frameUrl, target: "_blank", rel: "noopener noreferrer", children: "\u65B0\u6807\u7B7E\u9875\u6253\u5F00" }) : null, canSwitchMode ? (controlled
+                                ? _jsx("button", { type: "button", disabled: busy, onClick: () => void mutate('release'), children: "\u91CA\u653E\u8F93\u5165" })
+                                : _jsx("button", { type: "button", disabled: busy, onClick: () => void mutate('takeover'), children: "\u63A5\u7BA1\u8F93\u5165" })) : null] })] }), _jsx("div", { className: "wb-pane-feedback", role: "status", "aria-live": "polite", children: touch ? (controlled
+                    ? '当前身份在手机端也可直接输入。'
+                    : paneMode === 'unknown'
+                        ? '只读链接查看中，能否输入以终端页内的提示为准。'
+                        : '只读查看中。手机端为只读视图，需要输入请在电脑上操作。')
+                    : model.phase === 'loading' ? '正在检查终端权限…'
+                        : model.phase === 'taking-over' ? '正在接管输入…'
+                            : model.phase === 'releasing' ? '正在释放输入…'
+                                // 失败要连着「现在怎么办」一起说：只报错不说状态，用户会以为界面
+                                // 上写的只读就是真的（P1-3）。
+                                : model.error ? `${model.error.text}${model.phase === 'unknown' ? '；控制权状态未知，正在重新确认…' : ''}`
+                                    : model.phase === 'unknown' ? '控制权状态未知，正在重新确认…'
+                                        : control?.fixed ? '平台所有者身份已登录，可直接输入。'
+                                            : controlled ? '已接管，可键盘输入。'
+                                                // 没有接管能力的身份别劝人去点一个根本没渲染的按钮。
+                                                : props.authenticated && props.capabilities.canControl ? '只读查看中，点「接管输入」可操作。'
+                                                    : props.authenticated ? '只读查看中，当前身份不可接管输入。'
+                                                        : '只读查看。登录 Dashboard 后可接管。' }), _jsx("div", { className: "wb-pane-frame-shell", children: externalTerminalUrl ? (_jsxs("div", { className: "wb-pane-empty", children: [_jsx("span", { "aria-hidden": "true", children: "\u2197" }), _jsx("strong", { children: "\u5916\u90E8 Riff \u7EC8\u7AEF" }), _jsx("p", { children: "\u8BE5\u540E\u7AEF\u4E0D\u5728\u5DE5\u4F5C\u53F0\u9762\u677F\u5185\u5C55\u793A\u3002" }), _jsx("a", { href: externalTerminalUrl, target: "_blank", rel: "noopener noreferrer", children: "\u6253\u5F00\u5916\u90E8\u7EC8\u7AEF" })] })) : frameUrl ? (_jsxs(_Fragment, { children: [frameWithheld ? null : (_jsx("iframe", { ref: frameRef, className: "wb-pane-frame", src: frameUrl, title: `终端 — ${workbenchSessionTitle(props.session)}`, allow: "clipboard-read; clipboard-write", referrerPolicy: "no-referrer", onLoad: onFrameLoad }, frameKey)), frameWatch.blocked && !frameWithheld ? (_jsxs("div", { className: "wb-pane-empty wb-ws-blocked", role: "status", children: [_jsx("span", { "aria-hidden": "true", children: "\u26A0" }), _jsx("strong", { children: "\u7EC8\u7AEF\u5B9E\u65F6\u8FDE\u63A5\u672A\u5EFA\u7ACB" }), _jsx("p", { children: "\u5F53\u524D\u6D4F\u89C8\u5668\u73AF\u5883\u9650\u5236\u4E86\u975E\u52A0\u5BC6\u7684\u5B9E\u65F6\u8FDE\u63A5\uFF08iOS \u5185\u5E38\u89C1\uFF09\u3002\u53EF\u5C1D\u8BD5\u7528\u7CFB\u7EDF\u6D4F\u89C8\u5668\u6253\u5F00\uFF0C\u6216\u5728\u7535\u8111\u4E0A\u67E5\u770B\u3002" }), _jsx("a", { href: frameUrl, target: "_blank", rel: "noopener", children: "\u5728\u6D4F\u89C8\u5668\u4E2D\u6253\u5F00" }), _jsx("p", { children: "\u98DE\u4E66\u5185\u53EF\u901A\u8FC7\u53F3\u4E0A\u89D2 \u22EF \u83DC\u5355\u9009\u62E9\u300C\u5728\u6D4F\u89C8\u5668\u6253\u5F00\u300D\u3002" })] })) : null, masked ? _jsx(TerminalControlUnknown, { onRetry: () => void observe('reconcile') }) : null, !masked && withheldWhileChecking ? (_jsxs("div", { className: "wb-pane-empty wb-control-checking", role: "status", children: [_jsx("span", { "aria-hidden": "true", children: "\u22EF" }), _jsx("strong", { children: "\u6B63\u5728\u786E\u8BA4\u7EC8\u7AEF\u63A7\u5236\u6743" }), _jsx("p", { children: "\u786E\u8BA4\u4E4B\u524D\u5148\u4E0D\u63A5\u5165\u7EC8\u7AEF\u753B\u9762\uFF0C\u907F\u514D\u5728\u4E0D\u77E5\u9053\u80FD\u4E0D\u80FD\u5199\u7684\u60C5\u51B5\u4E0B\u628A\u8F93\u5165\u6253\u8FDB\u53BB\u3002" })] })) : null] })) : (touch || !props.authenticated) && !externalTerminalUrl && terminalUrl ? (
                 // A terminal exists, we just have no credential for it yet. Say so
                 // instead of framing a URL that would answer "Forbidden". 触屏即使已登录也走
                 // 这里：它等的是 viewToken 链接，同源地址对它等同于没有凭证。