@xcanwin/manyoyo 8.6.2 → 8.6.3

package/lib/web/server.js

@@ -23,7 +23,7 @@ const { isBrowserBackground } = require('../browser-background');
 const { createDeniedNotifier } = require('./denied-notify');
 const { domainRuleAllows } = require('../network-policy');
 const { createPortForwarder } = require('../port-forward');
-const { createContainerManageRoutes, pendingRisks } = require('./container-manage');
+const { createContainerManageRoutes, pendingRisks, STALE_PAGE_MESSAGE } = require('./container-manage');
 const { resolveManageOptions } = require('../container-manage-options');
 const { defaultPolicy, usesProxy } = require('../network-policy');
 const { normalizeMirrors } = require('../runtime-normalizers');
@@ -56,6 +56,9 @@ const {
     projectSessionEvents
 } = require('../core/events');
 const { FileEventStore } = require('../core/event-store');
+const historyStore = require('./history-store');
+const messagesView = require('./messages-view');
+const zlib = require('zlib');
 const { buildManyoyoLogPath, getLocalDateTag } = require('../log-path');
 const { isValidLogDateTag, readServeLogEntries } = require('../serve-log-reader');
 
@@ -68,6 +71,14 @@ const WEB_TERMINAL_DEFAULT_COLS = 120;
 const WEB_TERMINAL_DEFAULT_ROWS = 36;
 const WEB_TERMINAL_MIN_COLS = 40;
 const WEB_TERMINAL_MIN_ROWS = 12;
+// resize 的下限比建连时的 40×12 低：手机竖屏的真实列数可以小于 40，夹到 40 容器就会比网页宽、行尾被切
+const WEB_TERMINAL_RESIZE_MIN_COLS = 10;
+const WEB_TERMINAL_RESIZE_MIN_ROWS = 4;
+const WEB_TERMINAL_MAX_COLS = 500;
+const WEB_TERMINAL_MAX_ROWS = 200;
+// resize 节流：窗口拖动时前端虽有防抖，服务端仍保证两次容器内 stty 之间至少隔这么久
+const WEB_TERMINAL_RESIZE_MIN_INTERVAL_MS = 150;
+const WEB_TERMINAL_ID_PATTERN = /^[0-9a-f]{16}$/;
 // 终端 WebSocket 空闲心跳：纯交互式终端可能长时间没有任何数据，
 // 反向代理 / 移动网络的空闲超时（常见 60s）会悄悄掐断连接，这里定期发 ping
 // 帧制造流量。判死放宽到连续 3 次没回 pong（约 90s），手机切后台导致连接被
@@ -197,6 +208,8 @@ function createEmptyWebAgentSession(agentId, agentName) {
         createdAt: null,
         updatedAt: null,
         messages: [],
+        // 稳定前缀被改动时（删除非 pending 消息、克隆）必须换新值，增量同步据此让前端整页重置
+        epoch: messagesView.createEpoch(),
         events: [],
         lastResumeAt: null,
         lastResumeOk: null,
@@ -237,6 +250,9 @@ function normalizeWebAgentSessionRecord(agentId, rawAgent) {
         createdAt: typeof source.createdAt === 'string' ? source.createdAt : null,
         updatedAt: typeof source.updatedAt === 'string' ? source.updatedAt : null,
         messages: Array.isArray(source.messages) ? source.messages : [],
+        epoch: typeof source.epoch === 'string' && /^[0-9a-f]{8,32}$/.test(source.epoch)
+            ? source.epoch
+            : messagesView.createEpoch(),
         events: Array.isArray(source.events)
             ? source.events.filter(event => {
                 try {
@@ -342,40 +358,40 @@ function normalizeWebHistoryRecord(containerName, rawData) {
 function loadWebSessionHistory(webHistoryDir, containerName) {
     ensureWebHistoryDir(webHistoryDir);
     const filePath = getWebHistoryFile(webHistoryDir, containerName);
-    if (!fs.existsSync(filePath)) {
-        return normalizeWebHistoryRecord(containerName, {});
-    }
+    const cached = historyStore.read(filePath, raw => normalizeWebHistoryRecord(containerName, raw));
+    return cached ? cached.value : normalizeWebHistoryRecord(containerName, {});
+}
 
-    try {
-        return normalizeWebHistoryRecord(containerName, JSON.parse(fs.readFileSync(filePath, 'utf-8')));
-    } catch (e) {
-        return normalizeWebHistoryRecord(containerName, {});
-    }
+// 同一历史的内存版本号，/messages 的 ETag 用它（不用 mtime：同一毫秒内的两次写入会撞）
+function getWebSessionHistoryVersion(webHistoryDir, containerName) {
+    return historyStore.getVersion(getWebHistoryFile(webHistoryDir, containerName));
 }
 
-function saveWebSessionHistory(webHistoryDir, containerName, history) {
-    ensureWebHistoryDir(webHistoryDir);
-    const filePath = getWebHistoryFile(webHistoryDir, containerName);
-    const normalized = normalizeWebHistoryRecord(containerName, history);
-    const runtimeMeta = getAgentRuntimeMeta(normalized.agentPromptCommand || '');
-    const defaultAgent = getWebAgentSession(normalized, WEB_DEFAULT_AGENT_ID);
-    const legacyCompatible = {
-        ...normalized,
+function serializeWebHistory(history) {
+    const runtimeMeta = getAgentRuntimeMeta(history.agentPromptCommand || '');
+    return JSON.stringify({
+        ...history,
         agentProgram: runtimeMeta.agentProgram || '',
         resumeSupported: runtimeMeta.resumeSupported === true
-    };
-    if (defaultAgent) {
-        legacyCompatible.messages = Array.isArray(defaultAgent.messages) ? defaultAgent.messages : [];
-        legacyCompatible.lastResumeAt = defaultAgent.lastResumeAt || null;
-        legacyCompatible.lastResumeOk = typeof defaultAgent.lastResumeOk === 'boolean' ? defaultAgent.lastResumeOk : null;
-        legacyCompatible.lastResumeError = defaultAgent.lastResumeError || '';
-    }
-    fs.writeFileSync(filePath, JSON.stringify(legacyCompatible, null, 4));
+    });
+}
+
+// defer: 只改内存缓存，最迟 1 秒后落盘（流式过程中的 trace 快照用）；不传则立即原子写
+function saveWebSessionHistory(webHistoryDir, containerName, history, options = {}) {
+    ensureWebHistoryDir(webHistoryDir);
+    const filePath = getWebHistoryFile(webHistoryDir, containerName);
+    const value = options.defer === true ? history : normalizeWebHistoryRecord(containerName, history);
+    historyStore.write(filePath, value, serializeWebHistory, { defer: options.defer === true });
+}
+
+function flushWebSessionHistories() {
+    historyStore.flushAll();
 }
 
 function removeWebSessionHistory(webHistoryDir, containerName) {
     ensureWebHistoryDir(webHistoryDir);
     const filePath = getWebHistoryFile(webHistoryDir, containerName);
+    historyStore.remove(filePath);
     if (fs.existsSync(filePath)) {
         fs.unlinkSync(filePath);
     }
@@ -399,7 +415,9 @@ function removeContainerIdempotent(ctx, containerName) {
 function removeAllAgentHistoryArtifacts(webHistoryDir, containerName, agentIds) {
     const eventStore = new FileEventStore(webHistoryDir);
     (Array.isArray(agentIds) ? agentIds : []).forEach(agentId => {
-        eventStore.remove(buildWebSessionKey(containerName, agentId));
+        const aggregateId = buildWebSessionKey(containerName, agentId);
+        controlEventSeqCache.delete(`${path.resolve(webHistoryDir)}|${aggregateId}`);
+        eventStore.remove(aggregateId);
     });
 }
 
@@ -557,23 +575,56 @@ function appendWebSessionMessage(webHistoryDir, sessionRefOrContainerName, role,
     return message;
 }
 
-function appendWebSessionControlEvent(webHistoryDir, sessionRef, type, data = {}) {
+// 事件日志（FileEventStore）每条事件立即追加，而历史快照里的 events 是合并写盘的（强杀后可能落后）。
+// seq 必须以日志为准：进程内记住每个 aggregate 最后追加的 seq，第一次用时从日志读一次。
+const controlEventSeqCache = new Map();
+
+function resolveNextControlSeq(eventStore, cacheKey, aggregateId, snapshotEvents, refresh) {
+    let last = refresh ? undefined : controlEventSeqCache.get(cacheKey);
+    if (last === undefined) {
+        const logged = eventStore.read(aggregateId);
+        if (logged.length) {
+            last = logged[logged.length - 1].seq;
+        } else {
+            // 日志为空：只有旧版本留下的历史快照里有事件，沿用它的 seq
+            const lastSnapshot = snapshotEvents.length ? snapshotEvents[snapshotEvents.length - 1] : null;
+            last = lastSnapshot ? lastSnapshot.seq : 0;
+        }
+    }
+    return last + 1;
+}
+
+function appendWebSessionControlEvent(webHistoryDir, sessionRef, type, data = {}, options = {}) {
     const history = loadWebSessionHistory(webHistoryDir, sessionRef.containerName);
     const agentSession = getWebAgentSession(history, sessionRef.agentId, { create: true, includeArchived: true });
     const events = Array.isArray(agentSession.events) ? agentSession.events : [];
-    const lastEvent = events.length ? events[events.length - 1] : null;
-    const event = createControlEvent({
-        type,
-        aggregateId: buildWebSessionKey(sessionRef.containerName, sessionRef.agentId),
-        seq: lastEvent ? lastEvent.seq + 1 : 1,
-        data
-    });
+    const aggregateId = buildWebSessionKey(sessionRef.containerName, sessionRef.agentId);
+    const cacheKey = `${path.resolve(webHistoryDir)}|${aggregateId}`;
     const eventStore = new FileEventStore(webHistoryDir);
-    eventStore.append(event);
+    let event = null;
+    for (let attempt = 0; attempt < 2 && !event; attempt += 1) {
+        const candidate = createControlEvent({
+            type,
+            aggregateId,
+            seq: resolveNextControlSeq(eventStore, cacheKey, aggregateId, events, attempt > 0),
+            data
+        });
+        try {
+            eventStore.append(candidate);
+            event = candidate;
+        } catch (error) {
+            // 缓存的 seq 与日志对不上（日志被别处改过）：丢掉缓存按日志重算一次
+            controlEventSeqCache.delete(cacheKey);
+            if (attempt > 0) {
+                throw error;
+            }
+        }
+    }
+    controlEventSeqCache.set(cacheKey, event.seq);
     agentSession.events = [...events, event].slice(-WEB_HISTORY_MAX_MESSAGES);
     agentSession.updatedAt = event.timestamp;
     history.updatedAt = event.timestamp;
-    saveWebSessionHistory(webHistoryDir, sessionRef.containerName, history);
+    saveWebSessionHistory(webHistoryDir, sessionRef.containerName, history, { defer: options.defer === true });
     return event;
 }
 
@@ -591,7 +642,7 @@ function loadWebSessionControlEvents(webHistoryDir, sessionRef, fallbackEvents =
     return Array.isArray(fallbackEvents) ? fallbackEvents : [];
 }
 
-function patchWebSessionMessage(webHistoryDir, sessionRefOrContainerName, messageId, patch) {
+function patchWebSessionMessage(webHistoryDir, sessionRefOrContainerName, messageId, patch, options = {}) {
     const sessionRef = typeof sessionRefOrContainerName === 'string'
         ? { containerName: sessionRefOrContainerName, agentId: WEB_DEFAULT_AGENT_ID }
         : sessionRefOrContainerName;
@@ -615,7 +666,7 @@ function patchWebSessionMessage(webHistoryDir, sessionRefOrContainerName, messag
     const timestamp = new Date().toISOString();
     agentSession.updatedAt = timestamp;
     history.updatedAt = timestamp;
-    saveWebSessionHistory(webHistoryDir, sessionRef.containerName, history);
+    saveWebSessionHistory(webHistoryDir, sessionRef.containerName, history, { defer: options.defer === true });
     return message;
 }
 
@@ -634,6 +685,9 @@ function removeWebSessionMessage(webHistoryDir, sessionRefOrContainerName, messa
         return null;
     }
     const removed = agentSession.messages.splice(index, 1)[0] || null;
+    if (removed && removed.pending !== true) {
+        agentSession.epoch = messagesView.createEpoch();
+    }
     const timestamp = new Date().toISOString();
     agentSession.updatedAt = timestamp;
     history.updatedAt = timestamp;
@@ -2460,6 +2514,24 @@ function redactConfigObject(value) {
     return result;
 }
 
+function computeContentEtag(text) {
+    return crypto.createHash('sha256').update(String(text == null ? '' : text)).digest('hex');
+}
+
+// 规范化 If-Match：去掉引号和 W/ 前缀、统一小写；* 表示“只要存在就匹配”（原样保留）
+function normalizeIfMatchHeader(value) {
+    const text = String(value).trim();
+    if (text === '*') {
+        return '*';
+    }
+    return text.replace(/^W\//, '').replace(/"/g, '').trim().toLowerCase();
+}
+
+function ifMatchSatisfied(headerValue, currentEtag) {
+    const normalized = normalizeIfMatchHeader(headerValue);
+    return normalized === '*' || normalized === String(currentEtag).toLowerCase();
+}
+
 function buildSafeWebConfigSnapshot(snapshot, ctx) {
     const parsed = snapshot && snapshot.parseError ? {} : toPlainObject(snapshot && snapshot.parsed);
     let raw = '';
@@ -2480,6 +2552,8 @@ function buildSafeWebConfigSnapshot(snapshot, ctx) {
     return {
         path: snapshot && snapshot.path ? snapshot.path : path.resolve(getDefaultWebConfigPath()),
         raw,
+        // 版本号 = 磁盘原文的 sha256（不是脱敏后的文本：只有密钥变了也要能识别），只返回哈希，不泄露内容
+        etag: computeContentEtag(snapshot && typeof snapshot.raw === 'string' ? snapshot.raw : ''),
         parsed: redactConfigObject(parsed),
         defaults: redactConfigObject(buildConfigDefaults(ctx, parsed)),
         parseError: snapshot && snapshot.parseError ? snapshot.parseError : null,
@@ -3121,6 +3195,7 @@ function cloneWebAgentSessionsDeep(sourceHistory) {
         : {};
     Object.keys(agents).forEach(agentId => {
         cloned[agentId] = JSON.parse(JSON.stringify(agents[agentId]));
+        cloned[agentId].epoch = messagesView.createEpoch();
     });
     return cloned;
 }
@@ -3837,8 +3912,11 @@ function buildContainerFileReadCommand(requestedPath, options = {}) {
 const fs = require('fs');
 const path = require('path');
 
+const crypto = require('crypto');
+
 const requestedPath = ${JSON.stringify(String(requestedPath || ''))};
 const maxBytes = ${String(maxBytes)};
+const editMaxBytes = ${String(WEB_FILE_EDIT_MAX_BYTES)};
 const imageExtensions = new Set(${JSON.stringify(Object.keys(IMAGE_EXTENSION_CONTENT_TYPES))});
 
 function looksBinary(buffer) {
@@ -3889,11 +3967,18 @@ try {
                 truncated: maxBytes > 0 && size > maxBytes
             }));
         } else {
+            // 版本号：整个文件内容的 sha256（保存时带回来，容器里的文件被改过就能发现）；只给可编辑的小文件算
+            let etag = '';
+            if (size < editMaxBytes) {
+                const whole = readBytes === size ? buffer : fs.readFileSync(realPath);
+                etag = crypto.createHash('sha256').update(whole).digest('hex');
+            }
             process.stdout.write(JSON.stringify({
                 path: realPath,
                 kind: 'text',
                 size,
                 truncated: maxBytes > 0 && size > maxBytes,
+                etag,
                 content: buffer.toString('utf8')
             }));
         }
@@ -3931,12 +4016,17 @@ try {
 `);
 }
 
-function buildContainerFileWriteCommand(requestedPath, content) {
+// expectedEtag：读取时拿到的内容 sha256。写入前在容器里重新计算当前内容的哈希，不一致就不写（返回 conflict）。
+// 检查和写入之间仍有一个极短的窗口（同一个脚本里的两条语句之间），可以接受。
+function buildContainerFileWriteCommand(requestedPath, content, expectedEtag) {
     return buildWebContainerNodeCommand(`
 // __MANYOYO_FS_WRITE__
 const fs = require('fs');
+const crypto = require('crypto');
 
 const requestedPath = ${JSON.stringify(String(requestedPath || ''))};
+const editMaxBytes = ${String(WEB_FILE_EDIT_MAX_BYTES)};
+const expectedEtag = ${JSON.stringify(String(expectedEtag == null ? '' : expectedEtag))};
 const nextContent = ${JSON.stringify(String(content == null ? '' : content))};
 
 try {
@@ -3946,13 +4036,26 @@ try {
         throw new Error('目标不是文件: ' + realPath);
     }
 
-    fs.writeFileSync(realPath, nextContent, 'utf8');
-    const savedStat = fs.statSync(realPath);
-    process.stdout.write(JSON.stringify({
-        path: realPath,
-        saved: true,
-        size: savedStat.size
-    }));
+    // 太大的文件不整个读进内存比对：前端本来就不允许编辑，直接给明确的提示（而不是让用户看到“冲突”）
+    if (stat.size >= editMaxBytes) {
+        throw new Error('文件过大，当前仅支持编辑小于 2MB 的文本文件');
+    }
+    const currentEtag = crypto.createHash('sha256').update(fs.readFileSync(realPath)).digest('hex');
+    if (expectedEtag !== '*' && currentEtag !== expectedEtag) {
+        process.stdout.write(JSON.stringify({
+            conflict: true,
+            error: '文件已在容器里被修改'
+        }));
+    } else {
+        fs.writeFileSync(realPath, nextContent, 'utf8');
+        const savedStat = fs.statSync(realPath);
+        process.stdout.write(JSON.stringify({
+            path: realPath,
+            saved: true,
+            size: savedStat.size,
+            etag: crypto.createHash('sha256').update(Buffer.from(nextContent, 'utf8')).digest('hex')
+        }));
+    }
 } catch (e) {
     process.stdout.write(JSON.stringify({
         error: e && e.message ? e.message : '保存文件失败'
@@ -4243,22 +4346,140 @@ async function readJsonBody(req) {
     }
 }
 
-function sendJson(res, statusCode, payload, extraHeaders = {}) {
-    res.writeHead(statusCode, {
-        'Content-Type': 'application/json; charset=utf-8',
-        'Cache-Control': 'no-store',
+// 前端发送前为提示词生成的 id：服务端原样存进 user 消息，前端据此判断“这条是不是已经发出去了”
+function readClientMessageId(res, payload) {
+    const raw = payload && payload.clientMessageId;
+    if (raw === undefined || raw === null || raw === '') {
+        return { value: '' };
+    }
+    if (typeof raw !== 'string' || !messagesView.CLIENT_MESSAGE_ID_PATTERN.test(raw)) {
+        sendJson(res, 400, { error: 'clientMessageId 格式不正确' });
+        return null;
+    }
+    return { value: raw };
+}
+
+// 同一个 clientMessageId 已经出现在该 agent 的消息里：这条提示词服务端已经收到过，不能再执行一遍
+// （前端在网络中断后重发同一条时，靠它兜住“服务端其实已经收到”的情况）
+function rejectDuplicateClientMessage(res, webHistoryDir, sessionRef, clientMessageId) {
+    if (!clientMessageId) {
+        return false;
+    }
+    const history = loadWebSessionHistory(webHistoryDir, sessionRef.containerName);
+    const agentSession = getWebAgentSession(history, sessionRef.agentId, { includeArchived: true });
+    const duplicated = Boolean(agentSession) && agentSession.messages.some(
+        message => message && message.role === 'user' && message.clientMessageId === clientMessageId
+    );
+    if (!duplicated) {
+        return false;
+    }
+    sendJson(res, 409, { error: '这条消息已经发出过', duplicate: true });
+    return true;
+}
+
+// 检查重复到 user 消息落盘之间可能有 await（容器启动、网络规则就绪）：并发的同一条请求也要挡住
+const inflightClientMessages = new Set();
+
+// 返回 release()：消息落盘（或失败）后调用；已是重复则回 409 并返回 null
+function claimClientMessage(res, webHistoryDir, sessionRef, clientMessageId) {
+    if (!clientMessageId) {
+        return () => {};
+    }
+    if (rejectDuplicateClientMessage(res, webHistoryDir, sessionRef, clientMessageId)) {
+        return null;
+    }
+    const key = `${path.resolve(webHistoryDir)}|${buildWebSessionKey(sessionRef.containerName, sessionRef.agentId)}|${clientMessageId}`;
+    if (inflightClientMessages.has(key)) {
+        sendJson(res, 409, { error: '这条消息已经发出过', duplicate: true });
+        return null;
+    }
+    inflightClientMessages.add(key);
+    return () => inflightClientMessages.delete(key);
+}
+
+const COMPRESS_MIN_BYTES = 1024;
+
+function acceptsGzip(req) {
+    return Boolean(req && req.headers && /\bgzip\b/i.test(String(req.headers['accept-encoding'] || '')));
+}
+
+function etagMatches(req, etag) {
+    const header = req && req.headers ? String(req.headers['if-none-match'] || '') : '';
+    if (!header) {
+        return false;
+    }
+    if (header.trim() === '*') {
+        return true;
+    }
+    const strip = value => value.trim().replace(/^W\//, '');
+    return header.split(',').some(candidate => strip(candidate) === strip(etag));
+}
+
+// 统一的响应出口：可选 ETag（命中 If-None-Match 回 304）+ >1KB 的内容异步 gzip。
+// 只用于一次性 JSON/HTML；NDJSON 流和 WebSocket 不走这里，压缩会让它们被缓冲、失去实时性。
+function sendBody(res, statusCode, contentType, body, extraHeaders = {}, options = {}) {
+    const req = res.req;
+    const headers = {
+        'Content-Type': contentType,
+        'Cache-Control': options.etag ? 'no-cache' : 'no-store',
+        Vary: 'Accept-Encoding',
         ...extraHeaders
-    });
-    res.end(JSON.stringify(payload));
+    };
+    if (options.etag) {
+        headers.ETag = options.etag;
+        if (statusCode === 200 && etagMatches(req, options.etag)) {
+            delete headers['Content-Type'];
+            res.writeHead(304, headers);
+            res.end();
+            return;
+        }
+    }
+    const buffer = Buffer.isBuffer(body) ? body : Buffer.from(String(body), 'utf-8');
+    const finish = (payload, encoding) => {
+        if (res.destroyed || res.writableEnded) {
+            return;
+        }
+        if (encoding) {
+            headers['Content-Encoding'] = encoding;
+        }
+        headers['Content-Length'] = payload.length;
+        res.writeHead(statusCode, headers);
+        res.end(payload);
+    };
+    if (acceptsGzip(req) && buffer.length > COMPRESS_MIN_BYTES) {
+        const compressed = options.gzipBuffer
+            ? Promise.resolve(options.gzipBuffer)
+            : new Promise((resolve, reject) => {
+                zlib.gzip(buffer, { level: 6 }, (error, result) => (error ? reject(error) : resolve(result)));
+            });
+        compressed.then(result => finish(result, 'gzip'), () => finish(buffer, ''));
+        return;
+    }
+    finish(buffer, '');
+}
+
+// options.etag 传入时按它做条件请求；options.autoEtag 则用响应体的 sha1（响应体小、生成成本低的接口用）
+function sendJson(res, statusCode, payload, extraHeaders = {}, options = {}) {
+    const text = JSON.stringify(payload);
+    const etag = options.etag
+        || (options.autoEtag === true && statusCode === 200
+            ? `W/"${crypto.createHash('sha1').update(text).digest('hex')}"`
+            : '');
+    sendBody(res, statusCode, 'application/json; charset=utf-8', text, extraHeaders, { etag });
 }
 
 function sendNdjson(res, payload) {
     res.write(`${JSON.stringify(payload)}\n`);
 }
 
+const WEB_STREAM_FLUSH_EVENT_TYPES = new Set(['process.exited', 'process.interrupted', 'agent.turn.failed']);
+
 function createWebStreamEmitter(res, webHistoryDir, sessionRef) {
     return (payload, type, data = {}) => {
-        const controlEvent = appendWebSessionControlEvent(webHistoryDir, sessionRef, type, data);
+        // 流式过程中的事件只改内存（最迟 1 秒落盘）；结束类事件立即写盘，顺带写出之前攒着的内容
+        const controlEvent = appendWebSessionControlEvent(webHistoryDir, sessionRef, type, data, {
+            defer: !WEB_STREAM_FLUSH_EVENT_TYPES.has(type)
+        });
         sendNdjson(res, { ...payload, controlEvent });
     };
 }
@@ -4347,13 +4568,8 @@ function interruptOrphanPendingMessages(webHistoryDir, sessionRef) {
     saveWebSessionHistory(webHistoryDir, sessionRef.containerName, history);
 }
 
-function sendHtml(res, statusCode, html, extraHeaders = {}) {
-    res.writeHead(statusCode, {
-        'Content-Type': 'text/html; charset=utf-8',
-        'Cache-Control': 'no-store',
-        ...extraHeaders
-    });
-    res.end(html);
+function sendHtml(res, statusCode, html, extraHeaders = {}, options = {}) {
+    sendBody(res, statusCode, 'text/html; charset=utf-8', html, extraHeaders, options);
 }
 
 const SETUP_TEST_TIMEOUT_SECONDS = 60;
@@ -4738,11 +4954,54 @@ function buildSessionAudit(ctx, state, sessionRef) {
     };
 }
 
+// 按文件 mtime + size 缓存 index.html 原文（2MB，之前每次请求都同步读一遍）
+let indexHtmlCache = { key: '', html: '', variants: new Map() };
+
 function loadIndexHtml() {
-    if (!fs.existsSync(INDEX_HTML_PATH)) {
+    let stat = null;
+    try {
+        stat = fs.statSync(INDEX_HTML_PATH);
+    } catch (e) {
         return '<h1>Template Not Found</h1>';
     }
-    return fs.readFileSync(INDEX_HTML_PATH, 'utf-8');
+    const key = `${stat.ino}:${stat.mtimeMs}:${stat.size}`;
+    if (indexHtmlCache.key !== key) {
+        indexHtmlCache = { key, html: fs.readFileSync(INDEX_HTML_PATH, 'utf-8'), variants: new Map() };
+    }
+    return indexHtmlCache.html;
+}
+
+// 渲染结果（含 serveTitle 处理）+ ETag + gzip 都缓存，文件没变就不重算
+function getIndexHtmlVariant(kind, ctx) {
+    const html = loadIndexHtml();
+    const variantKey = `${kind}:${typeof ctx.serveTitle === 'string' ? ctx.serveTitle : ''}`;
+    let variant = indexHtmlCache.variants.get(variantKey);
+    if (!variant) {
+        const rendered = kind === 'app' ? renderAppHtml(ctx) : applyServeTitle(html, ctx);
+        variant = {
+            html: rendered,
+            etag: `W/"${crypto.createHash('sha1').update(rendered).digest('hex')}"`,
+            gzipBuffer: null
+        };
+        indexHtmlCache.variants.set(variantKey, variant);
+    }
+    return variant;
+}
+
+function sendIndexHtml(res, kind, ctx, extraHeaders = {}) {
+    const variant = getIndexHtmlVariant(kind, ctx);
+    const options = { etag: variant.etag };
+    if (variant.gzipBuffer) {
+        options.gzipBuffer = variant.gzipBuffer;
+    } else if (acceptsGzip(res.req)) {
+        // 第一次压缩的结果留着给后面的请求
+        zlib.gzip(Buffer.from(variant.html, 'utf-8'), { level: 6 }, (error, result) => {
+            if (!error) {
+                variant.gzipBuffer = result;
+            }
+        });
+    }
+    sendHtml(res, 200, variant.html, extraHeaders, options);
 }
 
 function escapeHtmlText(value) {
@@ -4823,7 +5082,31 @@ function sendTerminalEvent(ws, type, payload = {}) {
     ws.send(JSON.stringify({ type, ...payload }));
 }
 
-function spawnWebTerminalProcess(ctx, containerName, cols, rows) {
+// resize 消息的数值必须是整数且在范围内，否则整条忽略（不夹到边界，避免把异常值悄悄变成合法值）
+function parseTerminalResize(cols, rows) {
+    if (!Number.isInteger(cols) || !Number.isInteger(rows)) {
+        return null;
+    }
+    if (cols < WEB_TERMINAL_RESIZE_MIN_COLS || cols > WEB_TERMINAL_MAX_COLS
+        || rows < WEB_TERMINAL_RESIZE_MIN_ROWS || rows > WEB_TERMINAL_MAX_ROWS) {
+        return null;
+    }
+    return { cols, rows };
+}
+
+// 容器里跑的固定脚本，参数只有三个位置参数（终端 id、列、行），不经过 shell 拼接。
+// tty 文件在容器里，容器内的进程可以改写它，所以内容只当不可信输入：
+// 必须是普通文件（不跟符号链接、不碰 FIFO），读最多 64 字节，且整行匹配 /dev/pts/<数字> 才会执行 stty。
+const TERMINAL_RESIZE_SCRIPT = [
+    'f="/tmp/manyoyo-term-$1.tty"',
+    '[ -f "$f" ] && [ ! -L "$f" ] || exit 3',
+    't="$(head -c 64 "$f" 2>/dev/null | head -n 1)"',
+    'printf \'%s\\n\' "$t" | grep -Eq \'^/dev/pts/[0-9]+$\' || exit 4',
+    'case "$2$3" in *[!0-9]*) exit 5;; esac',
+    'exec stty -F "$t" cols "$2" rows "$3"'
+].join('\n');
+
+function spawnWebTerminalProcess(ctx, containerName, cols, rows, termId) {
     const terminalBootstrap = [
         'MANYOYO_WEB_BASHRC="$(mktemp /tmp/manyoyo-web-bashrc.XXXXXX 2>/dev/null || mktemp)"',
         'cat > "$MANYOYO_WEB_BASHRC" <<\'EOF_MANYOYO_RC\'',
@@ -4836,6 +5119,10 @@ function spawnWebTerminalProcess(ctx, containerName, cols, rows) {
         'if [ -f /run/manyoyo-sys/env.sh ]; then',
         '    . /run/manyoyo-sys/env.sh',
         'fi',
+        'if [ -n "${MANYOYO_TERM_ID:-}" ]; then',
+        '    tty > "/tmp/manyoyo-term-$MANYOYO_TERM_ID.tty" 2>/dev/null || true',
+        '    trap \'rm -f "/tmp/manyoyo-term-$MANYOYO_TERM_ID.tty"\' EXIT',
+        'fi',
         'if [ -n "${MANYOYO_TERM_COLS:-}" ] && [ -n "${MANYOYO_TERM_ROWS:-}" ]; then',
         '    COLUMNS="$MANYOYO_TERM_COLS"',
         '    LINES="$MANYOYO_TERM_ROWS"',
@@ -4865,7 +5152,8 @@ function spawnWebTerminalProcess(ctx, containerName, cols, rows) {
             `TERM=${termValue}`,
             `COLORTERM=${colorTermValue}`,
             `MANYOYO_TERM_COLS=${String(cols)}`,
-            `MANYOYO_TERM_ROWS=${String(rows)}`
+            `MANYOYO_TERM_ROWS=${String(rows)}`,
+            `MANYOYO_TERM_ID=${termId}`
         ],
         command: ['/bin/bash', '-lc', terminalBootstrap]
     }, { stdio: ['pipe', 'pipe', 'pipe'] });
@@ -4873,7 +5161,8 @@ function spawnWebTerminalProcess(ctx, containerName, cols, rows) {
 
 function bindTerminalWebSocket(ctx, state, ws, containerName, cols, rows) {
     const sessionId = `${containerName}-${Date.now()}-${Math.random().toString(16).slice(2, 8)}`;
-    const ptyProcess = spawnWebTerminalProcess(ctx, containerName, cols, rows);
+    const termId = crypto.randomBytes(8).toString('hex');
+    const ptyProcess = spawnWebTerminalProcess(ctx, containerName, cols, rows, termId);
     const session = {
         id: sessionId,
         containerName,
@@ -4916,6 +5205,10 @@ function bindTerminalWebSocket(ctx, state, ws, containerName, cols, rows) {
         }
         session.closing = true;
         clearInterval(pingTimer);
+        if (resizeState.timer) {
+            clearTimeout(resizeState.timer);
+            resizeState.timer = null;
+        }
         state.terminalSessions.delete(sessionId);
         if (ptyProcess && !ptyProcess.killed) {
             ptyProcess.kill('SIGTERM');
@@ -4927,6 +5220,72 @@ function bindTerminalWebSocket(ctx, state, ws, containerName, cols, rows) {
         }
     };
 
+    // 把前端新的窗口大小同步给容器里的伪终端，内核会自动给前台进程发 SIGWINCH。
+    // 数值严格校验；节流：同一时刻只有一个 exec 在跑，期间的新尺寸只保留最后一个
+    const resizeState = { running: false, pending: null, last: null, lastAt: 0, timer: null, retries: 0 };
+    const runTerminalResize = () => {
+        if (resizeState.running || !resizeState.pending || session.closing) {
+            return;
+        }
+        const wait = resizeState.lastAt + WEB_TERMINAL_RESIZE_MIN_INTERVAL_MS - Date.now();
+        if (wait > 0) {
+            if (!resizeState.timer) {
+                resizeState.timer = setTimeout(() => {
+                    resizeState.timer = null;
+                    runTerminalResize();
+                }, wait);
+            }
+            return;
+        }
+        const size = resizeState.pending;
+        resizeState.pending = null;
+        resizeState.running = true;
+        resizeState.lastAt = Date.now();
+        let child = null;
+        let killTimer = null;
+        const done = code => {
+            if (!resizeState.running) {
+                return;
+            }
+            clearTimeout(killTimer);
+            resizeState.running = false;
+            resizeState.lastAt = Date.now();
+            if (code !== 0 && !resizeState.pending && !session.closing && resizeState.retries < 3) {
+                // 失败（比如 tty 文件还没写好）：同尺寸的上报会被去重丢掉，所以这里自己重试几次
+                resizeState.retries += 1;
+                resizeState.pending = size;
+            } else if (code === 0) {
+                resizeState.retries = 0;
+            }
+            runTerminalResize();
+        };
+        try {
+            child = spawnContainerExec(ctx, containerName, {
+                command: ['/bin/bash', '-c', TERMINAL_RESIZE_SCRIPT, 'manyoyo-resize', termId, String(size.cols), String(size.rows)]
+            }, { stdio: 'ignore' });
+        } catch (e) {
+            done(1);
+            return;
+        }
+        killTimer = setTimeout(() => {
+            try { child.kill('SIGKILL'); } catch (e) { /* 已经退出 */ }
+        }, 5000);
+        child.once('close', code => done(code));
+        child.once('error', () => done(1));
+    };
+    const requestTerminalResize = (rawCols, rawRows) => {
+        const size = parseTerminalResize(rawCols, rawRows);
+        if (!size) {
+            return;
+        }
+        if (resizeState.last && resizeState.last.cols === size.cols && resizeState.last.rows === size.rows) {
+            return;
+        }
+        resizeState.last = size;
+        resizeState.pending = size;
+        runTerminalResize();
+    };
+
     ptyProcess.stdout.on('data', chunk => {
         sendTerminalEvent(ws, 'output', { data: chunk.toString('utf-8') });
     });
@@ -4973,7 +5332,7 @@ function bindTerminalWebSocket(ctx, state, ws, containerName, cols, rows) {
         }
 
         if (payload.type === 'resize') {
-            // 当前后端不直接驱动 docker exec 的 TTY 动态 resize，保留事件以便后续扩展。
+            requestTerminalResize(payload.cols, payload.rows);
             return;
         }
 
@@ -5037,7 +5396,7 @@ async function handleWebAuthRoutes(req, res, pathname, ctx, state) {
             });
             return true;
         }
-        sendHtml(res, 200, applyServeTitle(loadIndexHtml(), ctx), { 'Referrer-Policy': 'no-referrer' });
+        sendIndexHtml(res, 'login', ctx, { 'Referrer-Policy': 'no-referrer' });
         return true;
     }
 
@@ -5265,8 +5624,23 @@ async function handleWebApi(req, res, pathname, ctx, state) {
                     sendJson(res, 400, { error: '配置内容不能为空' });
                     return;
                 }
+                const ifMatch = req.headers['if-match'];
+                if (ifMatch === undefined) {
+                    sendJson(res, 428, { error: STALE_PAGE_MESSAGE });
+                    return;
+                }
 
+                // 从这里到写盘之间不能有 await：读文件、比对版本、写文件在同一个同步段里完成，并发的两个请求不会同时通过检查
                 const currentSnapshot = readWebConfigSnapshot(state.webConfigPath);
+                const currentEtag = computeContentEtag(currentSnapshot.raw);
+                if (!ifMatchSatisfied(ifMatch, currentEtag)) {
+                    sendJson(res, 409, {
+                        error: '配置文件已被其他地方修改',
+                        conflict: true,
+                        ...buildSafeWebConfigSnapshot(currentSnapshot, ctx)
+                    });
+                    return;
+                }
                 let finalRaw = raw;
                 let parsed = null;
                 try {
@@ -5283,6 +5657,7 @@ async function handleWebApi(req, res, pathname, ctx, state) {
                 sendJson(res, 200, {
                     saved: true,
                     path: savePath,
+                    etag: computeContentEtag(finalRaw),
                     defaults: buildConfigDefaults(ctx, parsed)
                 });
             }
@@ -5603,7 +5978,7 @@ async function handleWebApi(req, res, pathname, ctx, state) {
                     })
                     .sort(compareWebSessionCreatedDesc);
 
-                sendJson(res, 200, { sessions });
+                sendJson(res, 200, { sessions }, {}, { autoEtag: true });
             }
         },
         {
@@ -5743,14 +6118,62 @@ async function handleWebApi(req, res, pathname, ctx, state) {
                 if (!sessionRef) {
                     return;
                 }
+                const requestUrl = new URL(req.url || '/', 'http://localhost');
+                const query = messagesView.parseMessagesQuery(requestUrl.searchParams);
+                if (query.error) {
+                    sendJson(res, 400, { error: query.error });
+                    return;
+                }
                 const history = loadWebSessionHistory(state.webHistoryDir, sessionRef.containerName);
                 const agentSession = getWebAgentSession(history, sessionRef.agentId, { includeArchived: true })
                     || createEmptyWebAgentSession(sessionRef.agentId);
+                // 版本号来自历史缓存的进程内计数：不用算响应体就能判断 304，也不会像 mtime 那样在同一毫秒内撞车
+                const version = getWebSessionHistoryVersion(state.webHistoryDir, sessionRef.containerName);
+                const queryDigest = crypto.createHash('sha1')
+                    .update(`${sessionRef.agentId}|${requestUrl.search}`)
+                    .digest('hex')
+                    .slice(0, 12);
+                const etag = `W/"${historyStore.bootId}.${version}.${queryDigest}"`;
+                if (etagMatches(req, etag)) {
+                    sendJson(res, 200, {}, {}, { etag });
+                    return;
+                }
+                const view = messagesView.buildMessagesResponse(agentSession.messages, agentSession.epoch, query);
                 sendJson(res, 200, {
                     name: buildWebSessionKey(sessionRef.containerName, sessionRef.agentId),
                     containerName: sessionRef.containerName,
                     agentId: sessionRef.agentId,
-                    messages: agentSession.messages
+                    ...view
+                }, {}, { etag });
+            }
+        },
+        {
+            method: 'GET',
+            match: currentPath => currentPath.match(/^\/api\/sessions\/([^/]+)\/messages\/([^/]+)\/trace$/),
+            handler: async match => {
+                const sessionRef = getValidSessionRef(ctx, res, match[1]);
+                if (!sessionRef) {
+                    return;
+                }
+                const messageId = match[2];
+                if (!messagesView.MESSAGE_ID_PATTERN.test(messageId)) {
+                    sendJson(res, 400, { error: '消息 id 格式不正确' });
+                    return;
+                }
+                const history = loadWebSessionHistory(state.webHistoryDir, sessionRef.containerName);
+                const agentSession = getWebAgentSession(history, sessionRef.agentId, { includeArchived: true });
+                const message = agentSession
+                    ? agentSession.messages.find(item => item && item.id === messageId && item.streamTrace === true)
+                    : null;
+                if (!message) {
+                    sendJson(res, 404, { error: '没有找到这条执行过程' });
+                    return;
+                }
+                sendJson(res, 200, {
+                    id: message.id,
+                    content: message.content,
+                    traceEvents: Array.isArray(message.traceEvents) ? message.traceEvents : [],
+                    pending: message.pending === true
                 });
             }
         },
@@ -5905,12 +6328,22 @@ async function handleWebApi(req, res, pathname, ctx, state) {
                     return;
                 }
 
+                const ifMatch = req.headers['if-match'];
+                if (ifMatch === undefined) {
+                    sendJson(res, 428, { error: STALE_PAGE_MESSAGE });
+                    return;
+                }
+
                 await ensureWebContainer(ctx, state, sessionRef.containerName, sessionRef);
                 const result = await execJsonCommandInWebContainer(
                     ctx,
                     sessionRef.containerName,
-                    buildContainerFileWriteCommand(targetPath, content)
+                    buildContainerFileWriteCommand(targetPath, content, normalizeIfMatchHeader(ifMatch))
                 );
+                if (result && result.conflict === true) {
+                    sendJson(res, 409, { error: result.error || '文件已在容器里被修改', conflict: true });
+                    return;
+                }
                 if (result && result.error) {
                     sendJson(res, 400, { error: result.error });
                     return;
@@ -5985,7 +6418,7 @@ async function handleWebApi(req, res, pathname, ctx, state) {
 
                 const containerMap = listWebManyoyoContainers(ctx);
                 const detail = buildSessionDetail(ctx, state, containerMap, sessionRef);
-                sendJson(res, 200, { name: buildWebSessionKey(sessionRef.containerName, sessionRef.agentId), detail });
+                sendJson(res, 200, { name: buildWebSessionKey(sessionRef.containerName, sessionRef.agentId), detail }, {}, { autoEtag: true });
             }
         },
         {
@@ -6146,9 +6579,23 @@ async function handleWebApi(req, res, pathname, ctx, state) {
                     sendJson(res, 400, { error: 'command 不能为空' });
                     return;
                 }
-
-                await ensureWebContainer(ctx, state, sessionRef.containerName, sessionRef);
-                appendWebSessionMessage(state.webHistoryDir, sessionRef, 'user', command, { mode: 'command' });
+                const commandClientId = readClientMessageId(res, payload);
+                if (!commandClientId) {
+                    return;
+                }
+                const releaseCommandClaim = claimClientMessage(res, state.webHistoryDir, sessionRef, commandClientId.value);
+                if (!releaseCommandClaim) {
+                    return;
+                }
+                try {
+                    await ensureWebContainer(ctx, state, sessionRef.containerName, sessionRef);
+                    appendWebSessionMessage(state.webHistoryDir, sessionRef, 'user', command, {
+                        mode: 'command',
+                        ...(commandClientId.value ? { clientMessageId: commandClientId.value } : {})
+                    });
+                } finally {
+                    releaseCommandClaim();
+                }
                 const result = await execCommandInWebContainer(ctx, sessionRef.containerName, command);
                 // role 用 'system'、带 mode: 'command'，与前端实时发送时的约定对齐（workspace-panel.tsx
                 // handleSend 的 command 分支）——命令输出本来就不该走 assistant 的气泡样式和 markdown 渲染，
@@ -6178,11 +6625,20 @@ async function handleWebApi(req, res, pathname, ctx, state) {
                     sendJson(res, 400, { error: 'prompt 不能为空' });
                     return;
                 }
+                const agentClientId = readClientMessageId(res, payload);
+                if (!agentClientId) {
+                    return;
+                }
+                const releaseAgentClaim = claimClientMessage(res, state.webHistoryDir, sessionRef, agentClientId.value);
+                if (!releaseAgentClaim) {
+                    return;
+                }
 
                 let prepared = null;
                 try {
                     prepared = await prepareWebAgentExecution(ctx, state, sessionRef, prompt);
                 } catch (e) {
+                    releaseAgentClaim();
                     sendJson(res, 400, { error: e && e.message ? e.message : 'Agent 执行准备失败' });
                     return;
                 }
@@ -6190,8 +6646,10 @@ async function handleWebApi(req, res, pathname, ctx, state) {
                 const { agentSession, agentMeta, command, contextMode, resumeAttempted, resumeSucceeded, resumeError, engineSessionId } = prepared;
                 appendWebSessionMessage(state.webHistoryDir, sessionRef, 'user', prompt, {
                     mode: 'agent',
-                    contextMode
+                    contextMode,
+                    ...(agentClientId.value ? { clientMessageId: agentClientId.value } : {})
                 });
+                releaseAgentClaim();
                 const result = await execCommandInWebContainer(ctx, sessionRef.containerName, command, {
                     agentProgram: agentMeta.agentProgram
                 });
@@ -6227,6 +6685,13 @@ async function handleWebApi(req, res, pathname, ctx, state) {
                     sendJson(res, 400, { error: 'prompt 不能为空' });
                     return;
                 }
+                const streamClientId = readClientMessageId(res, payload);
+                if (!streamClientId) {
+                    return;
+                }
+                if (rejectDuplicateClientMessage(res, state.webHistoryDir, sessionRef, streamClientId.value)) {
+                    return;
+                }
                 if (state.agentRuns.has(sessionRef.containerName)) {
                     // 锁是容器级的：同一容器里其他 agent 会话在跑任务时同样命中这里
                     sendJson(res, 409, { error: '当前容器已有运行中的 agent 任务，请等它结束或先停止' });
@@ -6237,7 +6702,8 @@ async function handleWebApi(req, res, pathname, ctx, state) {
 
                 const userMessage = appendWebSessionMessage(state.webHistoryDir, sessionRef, 'user', prompt, {
                     mode: 'agent',
-                    pending: true
+                    pending: true,
+                    ...(streamClientId.value ? { clientMessageId: streamClientId.value } : {})
                 });
                 const traceMessage = appendWebAgentTraceMessage(
                     state.webHistoryDir,
@@ -6365,7 +6831,7 @@ async function handleWebApi(req, res, pathname, ctx, state) {
                             content: traceLines.join('\n'),
                             traceEvents: traceEvents.slice(),
                             pending: true
-                        });
+                        }, { defer: true });
                     }
                     if (event && event.type === 'content_delta' && typeof event.content === 'string') {
                         const now = Date.now();
@@ -6391,7 +6857,7 @@ async function handleWebApi(req, res, pathname, ctx, state) {
                             patchWebSessionMessage(state.webHistoryDir, sessionRef, streamingReplyMessageId, {
                                 content: event.content,
                                 pending: true
-                            });
+                            }, { defer: true });
                             lastPartialPersistAt = now;
                         }
                     }
@@ -6741,7 +7207,7 @@ async function startWebServer(options) {
 
             // 前端构建产物见 frontend/（npm run build:web），输出到 lib/web/index.html
             if (req.method === 'GET' && pathname === '/') {
-                sendHtml(res, 200, renderAppHtml(ctx));
+                sendIndexHtml(res, 'app', ctx);
                 return;
             }
 
@@ -6917,6 +7383,7 @@ async function startWebServer(options) {
         port: listenPort,
         close: () => new Promise(resolve => {
             ctx.logger.info('web server closing');
+            flushWebSessionHistories();
             if (state.networkWatch) {
                 state.networkWatch.stop();
                 state.networkWatch = null;
@@ -6956,5 +7423,14 @@ async function startWebServer(options) {
 
 module.exports = {
     startWebServer,
-    buildEnvModelOptions
+    buildEnvModelOptions,
+    // 仅供测试：直接驱动历史读写层
+    __testing: {
+        appendWebSessionMessage,
+        appendWebSessionControlEvent,
+        removeWebSessionMessage,
+        loadWebSessionHistory,
+        saveWebSessionHistory,
+        cloneWebAgentSessionsDeep
+    }
 };