@xcanwin/manyoyo 8.6.10 → 8.6.12

package/lib/web/server.js

@@ -19,7 +19,7 @@ const gitChanges = require('./git-changes');
 const { buildExecArgs, resolveContainerId, readMergedEnv } = require('../container-exec');
 const { createNetworkManager, NETWORK_NAME } = require('../container-network');
 const { normalizePolicy, isUnrestricted: isUnrestrictedPolicy } = require('../network-policy');
-const { withEnvEndpoints } = require('../network-endpoints');
+const { withEnvEndpoints, modelDomains, agentModelDomains } = require('../network-endpoints');
 const { egressPaths, isSidecarName } = require('../egress-sidecar');
 const { read: readDenied } = require('../egress-denied');
 const { isBrowserBackground } = require('../browser-background');
@@ -38,6 +38,11 @@ const { AGENT_ENV_SCHEMA } = require('../init-config');
 const { ensureImagePresent, pullImageProcess } = require('../image-pull');
 const { waitForImport } = require('../offline-import');
 const { baseRawOf, buildAgentConfigRaw, buildPasswordConfigRaw, shouldWriteMirrors, buildMirrorsConfigRaw, buildAgentInstructionsConfigRaw, buildBooleanConfigRaw } = require('../setup-config');
+const { createImageAgentProbe } = require('../image-agents');
+const { createAuthStore } = require('./auth-store');
+const webUploads = require('./uploads');
+const webSnapshots = require('./snapshots');
+const webRewind = require('./rewind');
 const { listSetupAgents, getConfiguredAgents, buildAgentRunProfile, classifyConnectionResult, redactSecrets, validateSetupPassword, listMirrorPresets } = require('../setup');
 const { applyDoctorFixes } = require('../doctor');
 const { writeConfigFileSecure } = require('../secure-file');
@@ -52,7 +57,7 @@ const {
     resolveAgentPromptCommandTemplate,
     buildAgentResumeCommand
 } = require('../agent-resume');
-const { resolveYoloCommand: resolveYoloCommandFromAdapters } = require('../agent-adapters');
+const { resolveYoloCommand: resolveYoloCommandFromAdapters, withCodexBaseUrl } = require('../agent-adapters');
 const {
     createControlEvent,
     validateControlEvent,
@@ -229,7 +234,9 @@ function createEmptyWebAgentSession(agentId, agentName) {
         title: '',
         firstPrompt: '',
         pinned: false,
-        slashCommands: null
+        slashCommands: null,
+        // 回退对话后，下一轮 Claude 命令带 --resume-session-at <uuid>（只用一次）
+        rewindToUuid: ''
     };
 }
 
@@ -287,7 +294,8 @@ function normalizeWebAgentSessionRecord(agentId, rawAgent) {
         title: sessionMeta.normalizeTitle(source.title),
         firstPrompt: sessionMeta.normalizeFirstPrompt(source.firstPrompt),
         pinned: source.pinned === true,
-        slashCommands: normalizeStoredSlashCommands(source.slashCommands)
+        slashCommands: normalizeStoredSlashCommands(source.slashCommands),
+        rewindToUuid: typeof source.rewindToUuid === 'string' && webRewind.UUID_PATTERN.test(source.rewindToUuid) ? source.rewindToUuid : ''
     };
 }
 
@@ -730,6 +738,53 @@ function removeWebSessionMessage(webHistoryDir, sessionRefOrContainerName, messa
     return removed;
 }
 
+// 删掉某条消息及之后的所有消息（回退对话）。改动的是稳定前缀，必须换新 epoch，增量同步据此让前端整页重置
+function removeWebSessionMessagesFrom(webHistoryDir, sessionRef, messageId) {
+    const history = loadWebSessionHistory(webHistoryDir, sessionRef.containerName);
+    const agentSession = getWebAgentSession(history, sessionRef.agentId, { includeArchived: true });
+    if (!agentSession) {
+        return [];
+    }
+    const index = agentSession.messages.findIndex(item => item && String(item.id || '') === String(messageId));
+    if (index === -1) {
+        return [];
+    }
+    const removed = agentSession.messages.splice(index);
+    agentSession.epoch = messagesView.createEpoch();
+    const timestamp = new Date().toISOString();
+    agentSession.updatedAt = timestamp;
+    history.updatedAt = timestamp;
+    saveWebSessionHistory(webHistoryDir, sessionRef.containerName, history);
+    return removed;
+}
+
+// 从页面隐藏 / 取消隐藏某一组（用户消息 + 它的执行过程 + 回复）：只改展示，agent 仍记得
+function setWebSessionTurnHidden(webHistoryDir, sessionRef, userMessageId, hidden) {
+    const history = loadWebSessionHistory(webHistoryDir, sessionRef.containerName);
+    const agentSession = getWebAgentSession(history, sessionRef.agentId, { includeArchived: true });
+    if (!agentSession) {
+        return 0;
+    }
+    const start = agentSession.messages.findIndex(item => item && String(item.id || '') === String(userMessageId) && item.role === 'user');
+    if (start === -1) {
+        return 0;
+    }
+    let end = start + 1;
+    while (end < agentSession.messages.length && agentSession.messages[end].role !== 'user') {
+        end += 1;
+    }
+    for (let i = start; i < end; i += 1) {
+        if (hidden) agentSession.messages[i].hidden = true;
+        else delete agentSession.messages[i].hidden;
+    }
+    agentSession.epoch = messagesView.createEpoch();
+    const timestamp = new Date().toISOString();
+    agentSession.updatedAt = timestamp;
+    history.updatedAt = timestamp;
+    saveWebSessionHistory(webHistoryDir, sessionRef.containerName, history);
+    return end - start;
+}
+
 function setWebSessionAgentPromptCommand(webHistoryDir, containerName, agentPromptCommand) {
     const history = loadWebSessionHistory(webHistoryDir, containerName);
     history.agentPromptCommand = normalizeAgentPromptCommandTemplate(agentPromptCommand, 'agentPromptCommand');
@@ -960,20 +1015,24 @@ function buildCodexAgentExecCommand(template, prompt, options = {}) {
         const modelFlag = model && !hasModel ? ` --model ${quoteBashSingleValue(model)}` : '';
         // 环境说明：模板里已经写了 developer_instructions 就以用户的为准
         const instructions = options && typeof options.instructions === 'string' ? options.instructions : '';
+        // 图片：--image=<路径>（等号形式只吃这一个值，不会把后面的提示词当成图片）；resume 子命令同样支持
+        const images = options && Array.isArray(options.images) ? options.images : [];
+        const imageFlags = images.map(item => ` --image=${quoteBashSingleValue(item)}`).join('');
         const instructionsFlag = instructions && !/developer_instructions/.test(suffix)
             ? ` -c ${quoteBashSingleValue(`developer_instructions=${toTomlBasicString(instructions)}`)}`
             : '';
         if (sessionId) {
             const promptIndex = suffix.indexOf('{prompt}');
             const resumeSuffix = `${suffix.slice(0, promptIndex)}${quoteBashSingleValue(sessionId)} ${suffix.slice(promptIndex)}`;
-            codexTemplate = `${prefix}codex exec resume${injectedFlags}${modelFlag}${instructionsFlag}${resumeSuffix}`;
+            codexTemplate = `${prefix}codex exec resume${injectedFlags}${modelFlag}${instructionsFlag}${imageFlags}${resumeSuffix}`;
         } else {
-            codexTemplate = `${prefix}codex exec${injectedFlags}${modelFlag}${instructionsFlag}${suffix}`;
+            codexTemplate = `${prefix}codex exec${injectedFlags}${modelFlag}${instructionsFlag}${imageFlags}${suffix}`;
         }
     }
-    return codexTemplate === templateText
+    // 兼容服务：OPENAI_BASE_URL 在容器里由 shell 展开成 -c openai_base_url=…（codex 不认这个环境变量，见 withCodexBaseUrl）
+    return withCodexBaseUrl(codexTemplate === templateText
         ? renderAgentPromptCommand(templateText, prompt)
-        : renderAgentPromptCommand(codexTemplate, prompt);
+        : renderAgentPromptCommand(codexTemplate, prompt));
 }
 
 function prependAgentFlags(commandText, matchPattern, flagSpecs) {
@@ -1010,6 +1069,10 @@ function buildClaudeAgentExecCommand(template, prompt, options = {}) {
     if (sessionId) {
         flagSpecs.push({ flag: `-r ${sessionId}`, pattern: /(?:^|\s)-r(?:\s|$)/ });
     }
+    const resumeAtUuid = options && typeof options.resumeAtUuid === 'string' && webRewind.UUID_PATTERN.test(options.resumeAtUuid) ? options.resumeAtUuid : '';
+    if (sessionId && resumeAtUuid) {
+        flagSpecs.push({ flag: `--resume-session-at ${resumeAtUuid}`, pattern: /(?:^|\s)--resume-session-at(?:\s|$)/ });
+    }
     const model = options && typeof options.model === 'string' ? options.model.trim() : '';
     if (model) {
         flagSpecs.push({ flag: `--model ${quoteBashSingleValue(model)}`, pattern: /(?:^|\s)--model(?:\s|$)/ });
@@ -2323,7 +2386,7 @@ function prepareCodexTraceEvent(payload) {
     });
 }
 
-async function prepareWebAgentExecution(ctx, state, sessionRef, prompt) {
+async function prepareWebAgentExecution(ctx, state, sessionRef, prompt, images = []) {
     const history = loadWebSessionHistory(state.webHistoryDir, sessionRef.containerName);
     const agentSession = getWebAgentSession(history, sessionRef.agentId, { create: true, includeArchived: true });
     const containerMap = listWebManyoyoContainers(ctx);
@@ -2377,9 +2440,12 @@ async function prepareWebAgentExecution(ctx, state, sessionRef, prompt) {
         }
     }
 
+    // Codex 用 --image 传图；其余 Agent 在提示词末尾写路径，让它们用读文件的工具去看
+    const imagesByFlag = agentMeta.agentProgram === 'codex';
+    const promptWithImages = imagesByFlag ? prompt : webUploads.appendImageNote(prompt, images);
     const effectivePrompt = resumeSucceeded
-        ? prompt
-        : buildAgentPromptWithHistory(agentSession, prompt);
+        ? promptWithImages
+        : buildAgentPromptWithHistory(agentSession, promptWithImages);
     // 环境说明每次执行时现读配置：改了设置不用重建容器；运行配置名记在创建时的快照里（旧会话没有，用全局配置）
     const configSnapshot = readWebConfigSnapshot(state.webConfigPath);
     const runName = history.runtimeSnapshot && typeof history.runtimeSnapshot.run === 'string' ? history.runtimeSnapshot.run : '';
@@ -2387,6 +2453,8 @@ async function prepareWebAgentExecution(ctx, state, sessionRef, prompt) {
         sessionId: sessionIdForRun,
         model: agentSession.model || '',
         forwardSubagentText: agentMeta.agentProgram === 'claude' ? 'auto' : false,
+        images: imagesByFlag ? images : [],
+        resumeAtUuid: agentSession.rewindToUuid || '',
         instructions: buildAgentInstructions(
             configSnapshot.parseError ? {} : configSnapshot.parsed,
             runName,
@@ -2418,9 +2486,11 @@ function finalizeWebAgentExecution(state, sessionRef, agentSession, agentMeta, m
         resumeAttempted: meta.resumeAttempted,
         resumeSucceeded: meta.resumeSucceeded,
         interrupted: result.interrupted === true,
+        ...(result.networkDenied ? { networkDenied: result.networkDenied } : {}),
         ...(turnUsage ? { usage: turnUsage } : {})
     });
     const patch = {
+        rewindToUuid: '',
         lastResumeAt: meta.resumeAttempted ? new Date().toISOString() : (agentSession.lastResumeAt || null),
         lastResumeOk: meta.resumeAttempted ? meta.resumeSucceeded : agentSession.lastResumeOk,
         lastResumeError: meta.resumeAttempted ? (meta.resumeSucceeded ? '' : meta.resumeError) : (agentSession.lastResumeError || '')
@@ -2442,6 +2512,129 @@ function finalizeWebAgentExecution(state, sessionRef, agentSession, agentMeta, m
     return replyMessage;
 }
 
+// 每轮前后各拍一次工作目录快照（影子 git，见 lib/web/snapshots.js）；失败 / 太大不影响这一轮，只是这一轮不能回退文件
+// 在容器里跑一段 bash 脚本并取 stdout（脚本里的路径 / 提交号都已转义或校验）。
+// 用 `bash -c` 而不是 execCommandInWebContainer 的 `/bin/bash -lc`：不走登录 shell，更快；也让测试里按 /bin/bash 识别 Agent 运行的假 docker 不会把它误当成一轮对话
+function runWebContainerScript(ctx, containerName, script, timeoutMs = 60000) {
+    return new Promise(resolve => {
+        let child;
+        try {
+            child = spawnContainerExec(ctx, containerName, { withEnv: false, command: ['bash', '-c', script] }, { stdio: ['ignore', 'pipe', 'ignore'] });
+        } catch (e) {
+            resolve('');
+            return;
+        }
+        let out = '';
+        const timer = setTimeout(() => child.kill('SIGKILL'), timeoutMs);
+        child.stdout.setEncoding('utf8');
+        child.stdout.on('data', chunk => { if (out.length < 4 * 1024 * 1024) out += chunk; });
+        child.once('close', () => { clearTimeout(timer); resolve(out); });
+        child.once('error', () => { clearTimeout(timer); resolve(out); });
+    });
+}
+
+async function takeWebSnapshot(ctx, state, sessionRef, label) {
+    const workDir = resolveWebSessionWorkDir(state, sessionRef);
+    if (!workDir || workDir === '/') {
+        return { skipped: 'unavailable' };
+    }
+    try {
+        return webSnapshots.parseSnapshotOutput(await runWebContainerScript(ctx, sessionRef.containerName, webSnapshots.buildSnapshotCommand(workDir, label), 15000));
+    } catch (e) {
+        return { skipped: 'unavailable' };
+    }
+}
+
+// 回退的目标必须是一条已经结束的 Agent 用户消息，且这个容器里没有任务在跑
+function findWebRewindTarget(state, sessionRef, messageId) {
+    if (state.agentRuns.has(sessionRef.containerName)) {
+        return { status: 409, error: '任务进行中，暂时不能回退' };
+    }
+    const history = loadWebSessionHistory(state.webHistoryDir, sessionRef.containerName);
+    const agentSession = getWebAgentSession(history, sessionRef.agentId, { includeArchived: true });
+    const id = String(messageId || '');
+    const message = agentSession && agentSession.messages.find(item => item && String(item.id || '') === id);
+    if (!message || message.role !== 'user' || message.mode === 'command') {
+        return { status: 404, error: '没有找到这条提示词' };
+    }
+    if (message.pending === true) {
+        return { status: 409, error: '这一轮还在进行中' };
+    }
+    return { history, agentSession, message };
+}
+
+async function rewindWebSession(ctx, state, sessionRef, messageId, scope) {
+    const target = findWebRewindTarget(state, sessionRef, messageId);
+    if (target.error) {
+        return target;
+    }
+    // 回退期间占住这个容器的运行锁：恢复脚本最长跑 2 分钟，这段时间里不能让新的一轮开跑（文件会被还原、新消息会被删）
+    const runState = reserveWebAgentRun(state, sessionRef);
+    try {
+        return await rewindWebSessionLocked(ctx, state, sessionRef, scope, target);
+    } finally {
+        releaseWebAgentRun(state, sessionRef.containerName, runState);
+    }
+}
+
+async function rewindWebSessionLocked(ctx, state, sessionRef, scope, target) {
+    const { history, agentSession, message } = target;
+    let filesRestored = false;
+    if (scope !== 'conversation') {
+        if (!webSnapshots.isSnapId(message.snapBefore)) {
+            return { status: 409, error: '这一轮没有文件快照，不能回退文件' };
+        }
+        await ensureWebContainer(ctx, state, sessionRef.containerName, sessionRef);
+        const out = await runWebContainerScript(ctx, sessionRef.containerName, webSnapshots.buildRestoreCommand(resolveWebSessionWorkDir(state, sessionRef), message.snapBefore), 120000);
+        const restored = webSnapshots.parseRestoreOutput(out);
+        if (!restored.ok) {
+            // 先要给“现在”拍一张快照（让回退本身能撤销）；有超过 20MB 的大文件或快照仓库超过 1GB 时拍不了，宁可不回退
+            if (restored.reason === 'too-large') {
+                return { status: 409, error: '工作目录里有超过 20MB 的大文件（或快照已超过 1GB），没法先给当前状态留快照，所以不能回退文件；只回退对话没有这个限制' };
+            }
+            return { status: 500, error: '恢复文件失败，工作目录没有改动' };
+        }
+        filesRestored = true;
+    }
+    let conversationMode = '';
+    if (scope !== 'files') {
+        const program = getAgentRuntimeMeta(resolveEffectiveAgentPromptCommandForSession(
+            history, sessionRef.agentId, (listWebManyoyoContainers(ctx)[sessionRef.containerName] || {}).defaultCommand
+        )).agentProgram;
+        let engineSessionId = agentSession.engineSessionId || '';
+        let rewindToUuid = '';
+        if (!engineSessionId) {
+            conversationMode = 'precise';
+        } else if (program === 'claude') {
+            const command = webRewind.buildClaudeRecordsCommand(engineSessionId);
+            const records = command ? webRewind.parseClaudeRecords(await runWebContainerScript(ctx, sessionRef.containerName, command, 30000)) : [];
+            const pick = webRewind.pickClaudeResumeAt(records, { text: message.content, timeMs: Date.parse(message.timestamp) });
+            if (pick.found && pick.uuid) {
+                rewindToUuid = pick.uuid;
+                conversationMode = 'precise';
+            } else if (pick.found) {
+                // 回退到第一轮：Claude 那边什么都不需要记得，开新会话
+                engineSessionId = '';
+                conversationMode = 'precise';
+            } else {
+                engineSessionId = '';
+                conversationMode = 'history';
+            }
+        } else {
+            // 其它 Agent 没有精确回退：丢掉引擎会话，下一轮用剩下的聊天记录注入（不丢数据，只丢工具调用等细节）
+            engineSessionId = '';
+            conversationMode = 'history';
+        }
+        const removed = removeWebSessionMessagesFrom(state.webHistoryDir, sessionRef, message.id);
+        if (!removed.length) {
+            return { status: 409, error: '这条提示词已经不在了' };
+        }
+        patchWebAgentSessionState(state.webHistoryDir, sessionRef, { engineSessionId, rewindToUuid });
+        appendWebSessionControlEvent(state.webHistoryDir, sessionRef, 'session.stopped', { reason: 'rewind', scope });
+    }
+    return { ok: true, scope, filesRestored, conversationMode, prompt: message.content, images: Array.isArray(message.images) ? message.images : [] };
+}
+
 function resolveWebSessionWorkDir(state, sessionRef) {
     const history = loadWebSessionHistory(state.webHistoryDir, sessionRef.containerName);
     const applied = history.applied && typeof history.applied === 'object' ? history.applied : {};
@@ -2537,48 +2730,21 @@ function parseCookies(req) {
     return cookies;
 }
 
-function pruneExpiredWebAuthSessions(state) {
-    const now = Date.now();
-    for (const [sessionId, session] of state.authSessions.entries()) {
-        if (!session || session.expiresAt <= now) {
-            state.authSessions.delete(sessionId);
-        }
-    }
-}
-
 function createWebAuthSession(state, username) {
-    pruneExpiredWebAuthSessions(state);
-    const sessionId = crypto.randomBytes(24).toString('hex');
-    state.authSessions.set(sessionId, {
-        username,
-        expiresAt: Date.now() + WEB_AUTH_TTL_SECONDS * 1000
-    });
-    return sessionId;
+    return state.authStore.create(username);
 }
 
 function getWebAuthSession(state, req) {
-    pruneExpiredWebAuthSessions(state);
-    const cookies = parseCookies(req);
-    const sessionId = cookies[WEB_AUTH_COOKIE_NAME];
+    const sessionId = parseCookies(req)[WEB_AUTH_COOKIE_NAME];
     if (!sessionId) return null;
-
-    const session = state.authSessions.get(sessionId);
-    if (!session) return null;
-    if (session.expiresAt <= Date.now()) {
-        state.authSessions.delete(sessionId);
-        return null;
-    }
-
-    // Sliding session expiration
-    session.expiresAt = Date.now() + WEB_AUTH_TTL_SECONDS * 1000;
-    return { sessionId, username: session.username };
+    const session = state.authStore.touch(sessionId);
+    return session ? { sessionId, username: session.username } : null;
 }
 
 function clearWebAuthSession(state, req) {
-    const cookies = parseCookies(req);
-    const sessionId = cookies[WEB_AUTH_COOKIE_NAME];
+    const sessionId = parseCookies(req)[WEB_AUTH_COOKIE_NAME];
     if (sessionId) {
-        state.authSessions.delete(sessionId);
+        state.authStore.remove(sessionId);
     }
 }
 
@@ -3132,6 +3298,33 @@ function buildStaticContainerRuntime(ctx, containerName) {
     };
 }
 
+function normalizeFirstConfig(value, sourceLabel) {
+    if (value === undefined || value === null) return {};
+    if (typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`${sourceLabel} 的 first 必须是对象(map)，例如 {"shell":"init.sh"}`);
+    }
+    return value;
+}
+
+// first.envFile 里已存在的文件内容 + first.env，后者优先（与 CLI 一致）；返回 KEY=VALUE 行
+function buildFirstEnvLines(firstResolved) {
+    const lines = [];
+    (firstResolved.envFile || []).forEach(file => {
+        const resolvedPath = expandHomeAliasPath(file);
+        if (!path.isAbsolute(resolvedPath)) {
+            throw new Error(`环境变量文件仅支持绝对路径: ${file}`);
+        }
+        if (!fs.existsSync(resolvedPath)) return;
+        containerState.parseEnvFileContent(fs.readFileSync(resolvedPath, 'utf-8')).entries
+            .forEach(entry => lines.push(`${entry.key}=${entry.value}`));
+    });
+    Object.entries(firstResolved.env || {}).forEach(([key, value]) => {
+        const parsed = parseEnvEntry(`${key}=${value}`);
+        lines.push(`${parsed.key}=${parsed.value}`);
+    });
+    return lines;
+}
+
 function buildCreateRuntime(ctx, state, payload) {
     const body = toPlainObject(payload);
     const requestOptions = toPlainObject(body.createOptions);
@@ -3157,6 +3350,13 @@ function buildCreateRuntime(ctx, state, payload) {
     const requestVolumeList = hasRequestVolumes ? normalizeStringArray(requestOptions.volumes, 'createOptions.volumes') : [];
     const requestPortList = hasRequestPorts ? normalizeStringArray(requestOptions.ports, 'createOptions.ports') : [];
 
+    // first（首次命令）：请求里带了就只用它（复制容器时来自快照，已合并过），否则全局 + runs.<name>
+    const hasRequestFirst = hasOwn(requestOptions, 'first');
+    const globalFirstConfig = hasRequestFirst ? {} : normalizeFirstConfig(config.first, '全局配置');
+    const runFirstConfig = hasRequestFirst
+        ? normalizeFirstConfig(requestOptions.first, 'createOptions')
+        : normalizeFirstConfig(runConfig.first, '运行配置');
+
     const resolvedBase = resolveRuntimeConfig({
         cliOptions: {
             hostPath: requestOptions.hostPath,
@@ -3171,8 +3371,8 @@ function buildCreateRuntime(ctx, state, payload) {
         },
         globalConfig: config,
         runConfig,
-        globalFirstConfig: {},
-        runFirstConfig: {},
+        globalFirstConfig,
+        runFirstConfig,
         defaults: {
             hostPath: ctx.hostPath,
             containerName: `my-${ctx.formatDate()}`,
@@ -3312,6 +3512,19 @@ function buildCreateRuntime(ctx, state, payload) {
         });
     }
 
+    const firstResolved = resolvedBase.first;
+    const firstCommand = String(firstResolved.exec.shell || '').trim()
+        ? `${firstResolved.exec.prefix || ''}${firstResolved.exec.shell}${firstResolved.exec.suffix || ''}`
+        : '';
+    // 写进快照的 first 已经是合并后的结果，复制容器时当作请求里的 first 使用
+    const firstSnapshot = {
+        shellPrefix: pickFirstString(runFirstConfig.shellPrefix, globalFirstConfig.shellPrefix),
+        shell: pickFirstString(runFirstConfig.shell, globalFirstConfig.shell),
+        shellSuffix: pickFirstString(runFirstConfig.shellSuffix, globalFirstConfig.shellSuffix),
+        env: firstResolved.env || {},
+        envFile: firstResolved.envFile || []
+    };
+
     return {
         containerName,
         hostPath,
@@ -3322,6 +3535,7 @@ function buildCreateRuntime(ctx, state, payload) {
         containerExtraArgs: Array.isArray(ctx.containerExtraArgs) ? ctx.containerExtraArgs.slice() : [],
         containerEnvs,
         envFiles,
+        first: firstCommand ? { command: firstCommand, envLines: buildFirstEnvLines(firstResolved) } : null,
         containerVolumes,
         containerPorts,
         autostart: manage.autostart,
@@ -3349,6 +3563,7 @@ function buildCreateRuntime(ctx, state, payload) {
             ports: resolvedBase.ports || [],
             autostart: manage.autostart,
             systemPrompt,
+            first: firstSnapshot,
             // 复制容器时端口暴露（宿主机端口会冲突）与 peers（按 id 引用别的容器）不带过去
             network: { ...manage.network, expose: [], peers: { inbound: [] } }
         },
@@ -3434,6 +3649,7 @@ function buildCloneCreateOptionsFromSnapshot(runtimeSnapshot, fallbackHistory) {
             ports: runtimeSnapshot.ports || [],
             autostart: runtimeSnapshot.autostart || '',
             systemPrompt: runtimeSnapshot.systemPrompt || undefined,
+            first: runtimeSnapshot.first || undefined,
             network: runtimeSnapshot.network || undefined,
             // 快照来自服务端、原容器创建时已确认过，复制不必再确认
             confirmRisk: runtimeSnapshot.network ? true : undefined
@@ -3636,6 +3852,22 @@ async function isWebImagePresent(ctx, imageRef) {
     }
 }
 
+// `images --format` 的输出 → [{ name, tag, id, created, size }]：去掉悬空镜像，只留版本号合规（x.y.z-后缀）的，同名同版本去重
+function parseWebImageList(output) {
+    const seen = new Set();
+    const images = [];
+    for (const line of String(output || '').split('\n')) {
+        const [name, tag, id, created, size] = line.split('\t').map(part => (part || '').trim());
+        if (!name || !tag || name === '<none>' || tag === '<none>') continue;
+        if (!/^[A-Za-z0-9][A-Za-z0-9._/:-]*$/.test(name) || !/^\d+\.\d+\.\d+-[A-Za-z0-9][A-Za-z0-9._-]*$/.test(tag)) continue;
+        const key = `${name}:${tag}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        images.push({ name, tag, id: id || '', created: created || '', size: size || '' });
+    }
+    return images;
+}
+
 function createImagePreparingError(message) {
     const error = new Error(message);
     error.statusCode = 409;
@@ -3729,7 +3961,7 @@ async function cleanupStaleSetupTestContainers(ctx) {
 }
 
 // Agent 一轮对话里，容器被过滤代理拦下的新域名（浏览器后台请求不算）：只在 allowlist 容器上轮询
-function createWebDeniedNotifier(ctx, sessionRef, emit) {
+function createWebDeniedNotifier(ctx, sessionRef, emit, modelOptions = {}) {
     try {
         const homeDir = ctx.homeDir || os.homedir();
         const id = resolveContainerId(ctx.dockerExecArgs, sessionRef.containerName);
@@ -3737,10 +3969,20 @@ function createWebDeniedNotifier(ctx, sessionRef, emit) {
         const deniedDir = egressPaths(homeDir).denied;
         const policyOf = () => normalizePolicy(containerState.readNetworkRaw(homeDir, id) || undefined);
         if (!usesProxy(policyOf())) return null;
+        // 模型域名：env 里的 URL 域名 + 该 Agent 没配 BASE_URL 时的官方域名；每次现读 env（用户可能刚改过）
+        const isModelHost = host => {
+            const envLines = [
+                ...containerState.readEnv(homeDir, id).entries.map(entry => `${entry.key}=${entry.value}`),
+                ...containerState.envFileEntries(homeDir, id).map(entry => `${entry.key}=${entry.value}`)
+            ];
+            return agentModelDomains(envLines, modelOptions.agentProgram).includes(String(host).toLowerCase());
+        };
         return createDeniedNotifier({
             read: () => readDenied(deniedDir, id),
             isIgnored: host => isBrowserBackground(host) || domainRuleAllows(policyOf(), host),
-            emit
+            emit,
+            isModelHost,
+            onModelDenied: modelOptions.onModelDenied
         });
     } catch (e) {
         return null;
@@ -3967,6 +4209,15 @@ async function ensureWebContainer(ctx, state, containerInput, messageSessionRef
             'system',
             `容器 ${runtime.containerName} 已创建并启动。`
         );
+        if (runtime.first) {
+            const firstResult = await runWebFirstCommand(ctx, runtime.containerName, runtime.first);
+            appendWebSessionMessage(
+                state.webHistoryDir,
+                messageSessionRef || runtime.containerName,
+                'system',
+                firstResult.exitCode === 0 ? '首次命令已执行' : formatWebFirstFailure(firstResult, runtime.first)
+            );
+        }
         return;
     }
 
@@ -3983,6 +4234,58 @@ async function ensureWebContainer(ctx, state, containerInput, messageSessionRef
     await getWebNetworkManager(ctx, state).ensureReady(runtime.containerName);
 }
 
+const WEB_FIRST_COMMAND_TIMEOUT_MS = 10 * 60 * 1000;
+const WEB_FIRST_COMMAND_OUTPUT_CHARS = 500;
+
+// 新建容器后执行一次 first（与 CLI 的 executeFirstCommand 同语义，经 buildExecArgs 带上 first.env）；
+// 失败只返回结果，不删容器、不抛错
+function runWebFirstCommand(ctx, containerName, first) {
+    return new Promise(resolve => {
+        const tail = createTailBuffer(WEB_FIRST_COMMAND_OUTPUT_CHARS * 4);
+        let settled = false;
+        let timer = null;
+        const finish = result => {
+            if (settled) return;
+            settled = true;
+            if (timer) clearTimeout(timer);
+            resolve({ ...result, output: tail.text() });
+        };
+        let child;
+        try {
+            child = spawnContainerExec(
+                ctx,
+                containerName,
+                { extraEnv: first.envLines, command: ['/bin/bash', '-c', first.command] },
+                { stdio: ['ignore', 'pipe', 'pipe'] }
+            );
+        } catch (e) {
+            tail.push(e && e.message ? e.message : '');
+            finish({ exitCode: 1 });
+            return;
+        }
+        timer = setTimeout(() => {
+            tail.push('\n[等了 10 分钟仍未结束，已停止等待（容器里的命令可能还在运行）]');
+            child.kill('SIGKILL');
+            finish({ exitCode: 124 });
+        }, ctx.firstCommandTimeoutMs || WEB_FIRST_COMMAND_TIMEOUT_MS);
+        for (const stream of [child.stdout, child.stderr]) {
+            stream.setEncoding('utf8');
+            stream.on('data', chunk => tail.push(chunk));
+        }
+        child.on('error', error => {
+            tail.push(error && error.message ? error.message : '');
+            finish({ exitCode: 1 });
+        });
+        child.on('close', (code, signal) => finish({ exitCode: typeof code === 'number' ? code : (signal ? 1 : 0) }));
+    });
+}
+
+function formatWebFirstFailure(result, first) {
+    const secrets = first.envLines.map(line => line.slice(line.indexOf('=') + 1));
+    const text = sanitizeServeLogText(redactSecrets(result.output, secrets)).trim().slice(-WEB_FIRST_COMMAND_OUTPUT_CHARS);
+    return `首次命令失败（退出码 ${result.exitCode}）：${text}`;
+}
+
 async function execCommandInWebContainer(ctx, containerName, command, options = {}) {
     const opts = options && typeof options === 'object' ? options : {};
     const agentProgram = typeof opts.agentProgram === 'string' ? opts.agentProgram : '';
@@ -4204,6 +4507,25 @@ try {
 `);
 }
 
+// 只判断路径是否存在（点击聊天里的路径时用）；不存在不是错误，返回 exists:false
+function buildContainerPathExistsCommand(requestedPath) {
+    return buildWebContainerNodeCommand(`
+// __MANYOYO_FS_EXISTS__
+const fs = require('fs');
+
+const requestedPath = ${JSON.stringify(String(requestedPath || ''))};
+
+let result = { exists: false };
+try {
+    const stat = fs.statSync(requestedPath);
+    result = { exists: true, type: stat.isDirectory() ? 'dir' : (stat.isFile() ? 'file' : 'other') };
+} catch (e) {
+    result = { exists: false };
+}
+process.stdout.write(JSON.stringify(result));
+`);
+}
+
 function buildContainerFileReadCommand(requestedPath, options = {}) {
     const opts = options && typeof options === 'object' ? options : {};
     const maxBytes = Number.isFinite(opts.maxBytes) && opts.maxBytes > 0
@@ -4930,7 +5252,7 @@ function dispatchNextQueued(ctx, state, sessionRef, { force = false } = {}) {
         }
         ctx.logger.warn('queued prompt put back', { session: buildWebSessionKey(sessionRef.containerName, sessionRef.agentId), reason });
     };
-    runWebAgentStreamTurn(ctx, state, sessionRef, item.text, item.clientMessageId || '', createHeadlessResponse())
+    runWebAgentStreamTurn(ctx, state, sessionRef, item.text, item.clientMessageId || '', createHeadlessResponse(), Array.isArray(item.images) ? item.images : [])
         .then(turn => {
             if (turn && turn.busy) putBack('busy');
             else if (turn && turn.error) putBack(turn.error);
@@ -4960,6 +5282,8 @@ function listLiveRunsInContainer(ctx, containerName) {
 // 容器里还有活着的 Agent 进程时不发：那是上一个 serve 留下的孤儿任务或另一个 serve 实例的任务，
 // 再开一轮会和它并发；排队保留，由用户在界面上“继续发送”
 async function resumeQueuedAgentTurns(ctx, state) {
+    // 先等启动对账：否则会在还挂着旧 pending 的会话上再开新一轮
+    try { await state.orphanReconcileReady; } catch (e) { /* 对账失败不影响排队恢复 */ }
     let containers = {};
     try {
         containers = listWebManyoyoContainers(ctx);
@@ -5073,10 +5397,135 @@ function interruptOrphanPendingMessages(webHistoryDir, sessionRef) {
     saveWebSessionHistory(webHistoryDir, sessionRef.containerName, history);
 }
 
+// ---- serve 启动对账 ----
+// serve 重启会丢掉内存里的运行登记，历史里留着 pending=true 的消息，前端据此永远显示“进行中”。
+// 启动时记下当时就 pending 的那批消息 id（之后新发起的轮次不碰），再按容器里是否还有活着的运行分两种处理：
+// 没有 → 立即标成已中断；还有（docker 下容器里的 agent 会比 serve 活得久）→ 每 5 秒查一次，跑完再标。
+const WEB_ORPHAN_POLL_MS = 5000;
+const ORPHAN_NOTE_INTERRUPTED = {
+    trace: '服务重启，本轮已中断',
+    reply: '服务重启时这一轮被中断了。可以发送“继续”让它接着做。'
+};
+const ORPHAN_NOTE_FINISHED = {
+    trace: '服务重启，本轮在后台跑完，结果未接收',
+    reply: '服务重启后这一轮在后台跑完了，但结果没能接收；可以发送“继续”让它总结。'
+};
+
+function collectStartupPending(ctx, state) {
+    const entries = [];
+    let names = [];
+    try {
+        names = listWebHistorySessionNames(state.webHistoryDir, ctx.isValidContainerName);
+    } catch (e) {
+        ctx.logger.warn('orphan reconcile: list history failed', { message: e && e.message });
+        return entries;
+    }
+    for (const containerName of names) {
+        try {
+            const history = loadWebSessionHistory(state.webHistoryDir, containerName);
+            for (const [agentId, agentSession] of Object.entries(history.agents || {})) {
+                const ids = (agentSession.messages || []).filter(message => message && message.pending === true).map(message => message.id);
+                if (ids.length) entries.push({ containerName, agentId, ids: new Set(ids) });
+            }
+        } catch (e) {
+            ctx.logger.warn('orphan reconcile: skip unreadable history', { container: containerName, message: e && e.message });
+        }
+    }
+    return entries;
+}
+
+// 只改启动时记下的那些消息；这一轮的执行过程末尾补一行，最终回复（没有流式半截回复就新建一条）写一句说明
+function finalizeOrphanEntry(ctx, state, entry, note) {
+    const sessionRef = { containerName: entry.containerName, agentId: entry.agentId };
+    const history = loadWebSessionHistory(state.webHistoryDir, entry.containerName);
+    const agentSession = getWebAgentSession(history, entry.agentId, { includeArchived: true });
+    if (!agentSession || !Array.isArray(agentSession.messages)) return;
+    const running = state.agentRuns.get(entry.containerName);
+    const newerRunInSession = Boolean(running && running.sessionRef && running.sessionRef.agentId === entry.agentId);
+    let touched = false;
+    let replied = false;
+    for (const message of agentSession.messages) {
+        if (!message || message.pending !== true || !entry.ids.has(message.id)) continue;
+        message.pending = false;
+        message.interrupted = true;
+        touched = true;
+        if (message.streamTrace) {
+            message.content = `${message.content || ''}\n[任务] ${note.trace}`;
+        } else if (message.streamingReply) {
+            message.streamingReply = false;
+            message.content = message.content ? `${message.content}\n\n${note.reply}` : note.reply;
+            replied = true;
+        }
+    }
+    if (!touched) return;
+    const timestamp = new Date().toISOString();
+    agentSession.updatedAt = timestamp;
+    history.updatedAt = timestamp;
+    saveWebSessionHistory(state.webHistoryDir, entry.containerName, history);
+    // 这个会话已经有新的一轮在跑：不在末尾插入说明，免得夹进新一轮的消息中间
+    if (!replied && !newerRunInSession) {
+        appendWebSessionMessage(state.webHistoryDir, sessionRef, 'assistant', note.reply, { mode: 'agent', interrupted: true });
+    }
+    appendWebSessionControlEvent(state.webHistoryDir, sessionRef, 'process.interrupted', { reason: 'serve-restart' });
+}
+
+function isWebContainerRunning(ctx, containerName) {
+    try {
+        return Boolean(ctx.containerExists(containerName)) && ctx.getContainerStatus(containerName) === 'running';
+    } catch (e) {
+        return false;
+    }
+}
+
+async function waitForRuntimeReady(ctx) {
+    const deadline = Date.now() + 10 * 60 * 1000;
+    while (ctx.runtimeState && ctx.runtimeState.status === 'starting' && Date.now() < deadline) {
+        await new Promise(resolve => setTimeout(resolve, 1000));
+    }
+}
+
+async function reconcileOrphanTurns(ctx, state) {
+    const entries = collectStartupPending(ctx, state);
+    if (!entries.length) return;
+    await waitForRuntimeReady(ctx);
+    const byContainer = new Map();
+    for (const entry of entries) {
+        if (!byContainer.has(entry.containerName)) byContainer.set(entry.containerName, []);
+        byContainer.get(entry.containerName).push(entry);
+    }
+    for (const [containerName, list] of byContainer) {
+        const live = isWebContainerRunning(ctx, containerName) ? await listLiveRunsInContainer(ctx, containerName) : [];
+        if (!live.length) {
+            for (const entry of list) {
+                try { finalizeOrphanEntry(ctx, state, entry, ORPHAN_NOTE_INTERRUPTED); } catch (e) { ctx.logger.warn('orphan reconcile failed', { container: containerName, message: e && e.message }); }
+            }
+            continue;
+        }
+        let checking = false;
+        const timer = setInterval(async () => {
+            if (checking) return;
+            checking = true;
+            try {
+                const stillLive = isWebContainerRunning(ctx, containerName) ? await listLiveRunsInContainer(ctx, containerName) : [];
+                if (stillLive.length) return;
+                clearInterval(timer);
+                state.orphanTimers.delete(timer);
+                for (const entry of list) {
+                    try { finalizeOrphanEntry(ctx, state, entry, ORPHAN_NOTE_FINISHED); } catch (e) { ctx.logger.warn('orphan reconcile failed', { container: containerName, message: e && e.message }); }
+                }
+            } finally {
+                checking = false;
+            }
+        }, ctx.orphanPollMs || WEB_ORPHAN_POLL_MS);
+        if (typeof timer.unref === 'function') timer.unref();
+        state.orphanTimers.add(timer);
+    }
+}
+
 // 一轮 agent 对话的完整流程（占锁 → 落盘 → 执行 → 收尾）。res 是 NDJSON 响应；
 // 排队的提示词在没有前端连接时由 createHeadlessResponse() 顶替，事件照常落盘。
 // 返回 { busy } / { error }（没开始）或 { started: true }（跑完了）
-async function runWebAgentStreamTurn(ctx, state, sessionRef, prompt, clientMessageId, res) {
+async function runWebAgentStreamTurn(ctx, state, sessionRef, prompt, clientMessageId, res, images = []) {
     if (state.agentRuns.has(sessionRef.containerName)) {
         // 锁是容器级的：同一容器里其他 agent 会话在跑任务时同样命中这里
         return { busy: true };
@@ -5090,6 +5539,7 @@ async function runWebAgentStreamTurn(ctx, state, sessionRef, prompt, clientMessa
         userMessage = appendWebSessionMessage(state.webHistoryDir, sessionRef, 'user', prompt, {
             mode: 'agent',
             pending: true,
+            ...(images.length ? { images } : {}),
             ...(clientMessageId ? { clientMessageId: clientMessageId } : {})
         });
         traceMessage = appendWebAgentTraceMessage(
@@ -5109,7 +5559,7 @@ async function runWebAgentStreamTurn(ctx, state, sessionRef, prompt, clientMessa
 
     let prepared = null;
     try {
-        prepared = await prepareWebAgentExecution(ctx, state, sessionRef, prompt);
+        prepared = await prepareWebAgentExecution(ctx, state, sessionRef, prompt, images);
     } catch (e) {
         releaseWebAgentRun(state, sessionRef.containerName, runState);
         removeWebSessionMessage(state.webHistoryDir, sessionRef, traceMessage && traceMessage.id);
@@ -5271,9 +5721,23 @@ async function runWebAgentStreamTurn(ctx, state, sessionRef, prompt, clientMessa
 
     };
     // 有域名规则时被过滤代理拦下的新域名：对话进行中立即提示一次
-    const deniedNotifier = createWebDeniedNotifier(ctx, sessionRef, text => handleStreamEvent({ type: 'trace', stream: 'stdout', text }));
+    // 被拦的是 Agent 自己的模型域名：继续等只会白等到超时，立即中止本轮（不暂停排队，不是用户点的停止）
+    const deniedNotifier = createWebDeniedNotifier(ctx, sessionRef, text => handleStreamEvent({ type: 'trace', stream: 'stdout', text }), {
+        agentProgram: agentMeta.agentProgram,
+        onModelDenied: host => {
+            if (runState.modelDenied) return;
+            runState.modelDenied = host;
+            handleStreamEvent({ type: 'network_denied', host, model: true });
+            runState.stopping = true;
+            if (runState.process) terminateWebAgentRun(ctx, runState);
+        }
+    });
+    let snapBefore = { skipped: 'unavailable' };
     try {
         if (deniedNotifier) deniedNotifier.start();
+        snapBefore = await takeWebSnapshot(ctx, state, sessionRef, `web ${userMessage && userMessage.id} before`);
+        patchWebSessionMessage(state.webHistoryDir, sessionRef, userMessage && userMessage.id,
+            snapBefore.sha ? { snapBefore: snapBefore.sha } : { snapSkipped: snapBefore.skipped });
         let result;
         try {
             result = await execAgentInWebContainerStream(ctx, state, sessionRef, command, {
@@ -5291,14 +5755,21 @@ async function runWebAgentStreamTurn(ctx, state, sessionRef, prompt, clientMessa
             exitCode: result.exitCode,
             interrupted: result.interrupted === true
         });
-        traceLines.push(result.interrupted === true
-            ? (runState.steered && runState.userStopped !== true ? '[任务] 已打断，继续执行新的提示词' : '[任务] 已停止')
-            : '[任务] 已完成');
+        const modelDeniedHost = runState.modelDenied || '';
+        traceLines.push(modelDeniedHost
+            ? '[任务] 已中止：模型地址被网络策略拦截'
+            : (result.interrupted === true
+                ? (runState.steered && runState.userStopped !== true ? '[任务] 已打断，继续执行新的提示词' : '[任务] 已停止')
+                : '[任务] 已完成'));
+        const snapAfter = snapBefore.sha
+            ? await takeWebSnapshot(ctx, state, sessionRef, `web ${userMessage && userMessage.id} after`)
+            : { skipped: snapBefore.skipped };
         patchWebSessionMessage(state.webHistoryDir, sessionRef, userMessage && userMessage.id, {
             pending: false,
             contextMode,
             resumeAttempted,
-            resumeSucceeded
+            resumeSucceeded,
+            ...(snapAfter.sha ? { snapAfter: snapAfter.sha } : {})
         });
         patchWebSessionMessage(state.webHistoryDir, sessionRef, traceMessage && traceMessage.id, {
             content: traceLines.join('\n'),
@@ -5312,26 +5783,30 @@ async function runWebAgentStreamTurn(ctx, state, sessionRef, prompt, clientMessa
         if (streamingReplyMessageId) {
             removeWebSessionMessage(state.webHistoryDir, sessionRef, streamingReplyMessageId);
         }
+        const finalResult = modelDeniedHost
+            ? { ...result, interrupted: true, output: `已中止：模型地址 ${modelDeniedHost} 被网络策略拦截。`, networkDenied: { host: modelDeniedHost, model: true } }
+            : result;
         const replyMessage = finalizeWebAgentExecution(state, sessionRef, agentSession, agentMeta, {
             contextMode,
             resumeAttempted,
             resumeSucceeded,
             resumeError,
             engineSessionId
-        }, result);
+        }, finalResult);
         void refreshWebAgentTitle(ctx, state, sessionRef, agentMeta.agentProgram);
         emitStreamEvent({
             type: 'result',
-            exitCode: result.exitCode,
-            output: result.output,
+            exitCode: finalResult.exitCode,
+            output: finalResult.output,
+            ...(finalResult.networkDenied ? { networkDenied: finalResult.networkDenied } : {}),
             // 最终 assistant 消息的持久化 id：前端把 __streaming__ 占位换成它，
             // 发送后的首次对账才不会重建整个消息列表 DOM（滚动位置/选区保持）
             replyMessageId: replyMessage && replyMessage.id,
             contextMode,
             resumeAttempted,
             resumeSucceeded,
-            interrupted: result.interrupted === true
-        }, result.interrupted === true ? 'process.interrupted' : 'process.exited', { exitCode: result.exitCode });
+            interrupted: finalResult.interrupted === true
+        }, finalResult.interrupted === true ? 'process.interrupted' : 'process.exited', { exitCode: result.exitCode });
     } catch (e) {
         ctx.logger.error('agent turn failed', {
             session: turnSessionKey,
@@ -5339,11 +5814,15 @@ async function runWebAgentStreamTurn(ctx, state, sessionRef, prompt, clientMessa
             message: e && e.message ? e.message : 'Agent 执行失败'
         });
         traceLines.push(`[错误] ${e && e.message ? e.message : 'Agent 执行失败'}`);
+        const failedSnapAfter = snapBefore.sha
+            ? await takeWebSnapshot(ctx, state, sessionRef, `web ${userMessage && userMessage.id} after`)
+            : { skipped: snapBefore.skipped };
         patchWebSessionMessage(state.webHistoryDir, sessionRef, userMessage && userMessage.id, {
             pending: false,
             contextMode,
             resumeAttempted,
-            resumeSucceeded
+            resumeSucceeded,
+            ...(failedSnapAfter.sha ? { snapAfter: failedSnapAfter.sha } : {})
         });
         patchWebSessionMessage(state.webHistoryDir, sessionRef, traceMessage && traceMessage.id, {
             content: traceLines.join('\n'),
@@ -5365,7 +5844,7 @@ async function runWebAgentStreamTurn(ctx, state, sessionRef, prompt, clientMessa
         clearInterval(heartbeatTimer);
         clearTimeout(runState.stepTimer);
         // 用户停止的不自动发；其余（完成 / 失败 / 被追加打断）有排队就接着发队首
-        const hasNext = runState.userStopped !== true && agentQueue.shouldAutoDispatch(peekAgentSession(state, sessionRef));
+        const hasNext = runState.userStopped !== true && !runState.modelDenied && agentQueue.shouldAutoDispatch(peekAgentSession(state, sessionRef));
         if (hasNext && !res.writableEnded && !res.destroyed) {
             // 前端收到后改为跟随下一轮（走掉线恢复的那套轮询）
             sendNdjson(res, { type: 'queue_next' });
@@ -5416,6 +5895,15 @@ async function inspectSetupImage(ctx, state) {
     }
 }
 
+// 镜像里装了哪些 Agent CLI；镜像没就绪或探测失败返回 null（未知，向导照常可选）
+async function probeSetupImageAgents(ctx, state) {
+    if (!ctx.dockerExecAsync) return null;
+    const image = await inspectSetupImage(ctx, state);
+    if (image.status !== 'ready') return null;
+    if (!state.imageAgentProbe) state.imageAgentProbe = createImageAgentProbe(ctx.dockerExecAsync);
+    return state.imageAgentProbe(image.name);
+}
+
 // 在一次性容器里用所选 Agent 发一次最小请求；容器无论成败都会删除。
 async function runSetupConnectionTest(ctx, state, agent, envMap) {
     const secrets = Object.values(envMap);
@@ -5429,7 +5917,7 @@ async function runSetupConnectionTest(ctx, state, agent, envMap) {
     if (!template) {
         return { category: 'other', message: `${spec.label} 暂不支持连接测试`, detail: '' };
     }
-    const agentCommand = renderAgentPromptCommand(template, SETUP_TEST_PROMPT);
+    const agentCommand = withCodexBaseUrl(renderAgentPromptCommand(template, SETUP_TEST_PROMPT));
     const command = `timeout ${SETUP_TEST_TIMEOUT_SECONDS} /bin/bash -lc ${quoteBashSingleValue(agentCommand)}`;
 
     const workpath = getSetupWorkpath(state);
@@ -6541,11 +7029,35 @@ async function handleWebApi(req, res, pathname, ctx, state) {
                 sendJson(res, 200, await buildSetupStatus(ctx, state));
             }
         },
+        {
+            // 本机已有的镜像（系统设置「基础」里选镜像名 / 版本用）：只列版本号符合 x.y.z-后缀 的，按镜像名分组
+            method: 'GET',
+            match: currentPath => currentPath === '/api/images' ? [] : null,
+            handler: async () => {
+                const defaults = { imageName: ctx.imageName || '', imageVersion: ctx.imageVersion || '' };
+                if (!ctx.dockerExecAsync || !ctx.runtimeState || ctx.runtimeState.status !== 'ready') {
+                    sendJson(res, 200, { defaults, images: [] });
+                    return;
+                }
+                let output = '';
+                try {
+                    output = String(await ctx.dockerExecAsync(['images', '-a', '--format', '{{.Repository}}\t{{.Tag}}\t{{.ID}}\t{{.CreatedSince}}\t{{.Size}}'], { timeout: 15000 }) || '');
+                } catch (e) {
+                    output = '';
+                }
+                sendJson(res, 200, { defaults, images: parseWebImageList(output) });
+            }
+        },
         {
             method: 'GET',
             match: currentPath => currentPath === '/api/setup/agents' ? [] : null,
             handler: async () => {
-                sendJson(res, 200, { agents: listSetupAgents(), mirrorPresets: listMirrorPresets() });
+                const installed = await probeSetupImageAgents(ctx, state);
+                const agents = listSetupAgents().map(agent => ({
+                    ...agent,
+                    available: installed ? installed.includes(agent.id) : null
+                }));
+                sendJson(res, 200, { agents, mirrorPresets: listMirrorPresets() });
             }
         },
         {
@@ -7100,6 +7612,69 @@ async function handleWebApi(req, res, pathname, ctx, state) {
                 sendJson(res, 200, payload);
             }
         },
+        {
+            // 聊天里的图片：原始请求体，类型只收 png/jpeg/gif/webp，单张 10MB
+            method: 'POST',
+            match: currentPath => currentPath.match(/^\/api\/sessions\/([^/]+)\/uploads$/),
+            handler: async match => {
+                const sessionRef = getValidSessionRef(ctx, res, match[1]);
+                if (!sessionRef) {
+                    return;
+                }
+                const ext = webUploads.extForContentType(req.headers['content-type']);
+                if (!ext) {
+                    sendJson(res, 415, { error: '只支持 png、jpeg、gif、webp 图片' });
+                    return;
+                }
+                const declared = Number(req.headers['content-length']);
+                if (Number.isFinite(declared) && declared > webUploads.MAX_IMAGE_BYTES) {
+                    sendJson(res, 413, { error: '图片不能超过 10MB' });
+                    return;
+                }
+                if (!ctx.containerExists(sessionRef.containerName)) {
+                    sendJson(res, 404, { error: `容器不存在: ${sessionRef.containerName}` });
+                    return;
+                }
+                const homeDir = ctx.homeDir || os.homedir();
+                const id = resolveContainerId(ctx.dockerExecArgs, sessionRef.containerName);
+                if (!id || !containerState.stateExists(homeDir, id)) {
+                    sendJson(res, 409, { error: '这个容器太旧，不支持发图片，重建后可用' });
+                    return;
+                }
+                const saved = await webUploads.saveUpload(req, path.join(containerState.paths(homeDir, id).box, 'uploads'), ext);
+                if (!saved.ok) {
+                    sendJson(res, saved.status, { error: saved.error });
+                    return;
+                }
+                sendJson(res, 200, { path: `${webUploads.CONTAINER_UPLOAD_DIR}/${saved.name}` });
+            }
+        },
+        {
+            method: 'GET',
+            match: currentPath => currentPath.match(/^\/api\/sessions\/([^/]+)\/fs\/stat$/),
+            handler: async match => {
+                const sessionRef = getValidSessionRef(ctx, res, match[1]);
+                if (!sessionRef) {
+                    return;
+                }
+                const requestUrl = new URL(req.url || '/api/sessions/x/fs/stat', 'http://localhost');
+                const targetPath = String(requestUrl.searchParams.get('path') || '').trim();
+                // 点一下文字不该拉起容器：没在运行就当作不存在
+                if (!targetPath || !ctx.containerExists(sessionRef.containerName) || ctx.getContainerStatus(sessionRef.containerName) !== 'running') {
+                    sendJson(res, 200, { exists: false });
+                    return;
+                }
+                let payload = null;
+                try {
+                    payload = await execJsonCommandInWebContainer(ctx, sessionRef.containerName, buildContainerPathExistsCommand(targetPath));
+                } catch (e) {
+                    payload = null;
+                }
+                sendJson(res, 200, payload && payload.exists === true
+                    ? { exists: true, type: payload.type }
+                    : { exists: false });
+            }
+        },
         {
             method: 'GET',
             match: currentPath => currentPath.match(/^\/api\/sessions\/([^/]+)\/fs\/read$/),
@@ -7320,6 +7895,130 @@ async function handleWebApi(req, res, pathname, ctx, state) {
                 sendJson(res, 200, { name: buildWebSessionKey(sessionRef.containerName, sessionRef.agentId), detail }, {}, { autoEtag: true });
             }
         },
+        {
+            // 按轮看改动：比较某一轮前后两个快照（提交号必须是 40 位小写十六进制）
+            method: 'GET',
+            match: currentPath => currentPath.match(/^\/api\/sessions\/([^/]+)\/git\/rounds\/changes$/),
+            handler: async match => {
+                const sessionRef = getValidSessionRef(ctx, res, match[1]);
+                if (!sessionRef) {
+                    return;
+                }
+                const requestUrl = new URL(req.url || '/', 'http://localhost');
+                const from = String(requestUrl.searchParams.get('from') || '');
+                const to = String(requestUrl.searchParams.get('to') || '');
+                if (!webSnapshots.isSnapId(from) || !webSnapshots.isSnapId(to)) {
+                    sendJson(res, 400, { error: '快照号不合法' });
+                    return;
+                }
+                await ensureWebContainer(ctx, state, sessionRef.containerName, sessionRef);
+                const out = await runWebContainerScript(ctx, sessionRef.containerName, webSnapshots.buildRoundChangesCommand(resolveWebSessionWorkDir(state, sessionRef), from, to), 30000);
+                sendJson(res, 200, webSnapshots.parseRoundChangesOutput(out));
+            }
+        },
+        {
+            method: 'GET',
+            match: currentPath => currentPath.match(/^\/api\/sessions\/([^/]+)\/git\/rounds\/diff$/),
+            handler: async match => {
+                const sessionRef = getValidSessionRef(ctx, res, match[1]);
+                if (!sessionRef) {
+                    return;
+                }
+                const requestUrl = new URL(req.url || '/', 'http://localhost');
+                const from = String(requestUrl.searchParams.get('from') || '');
+                const to = String(requestUrl.searchParams.get('to') || '');
+                const filePath = String(requestUrl.searchParams.get('path') || '');
+                if (!webSnapshots.isSnapId(from) || !webSnapshots.isSnapId(to)) {
+                    sendJson(res, 400, { error: '快照号不合法' });
+                    return;
+                }
+                if (!gitChanges.isAcceptableDiffPath(filePath)) {
+                    sendJson(res, 400, { error: '文件路径不合法' });
+                    return;
+                }
+                await ensureWebContainer(ctx, state, sessionRef.containerName, sessionRef);
+                const workDir = resolveWebSessionWorkDir(state, sessionRef);
+                // 只给这两个快照之间出现过的文件看 diff：路径由服务端重新取一次核对，不信任请求
+                const listed = webSnapshots.parseRoundChangesOutput(await runWebContainerScript(ctx, sessionRef.containerName, webSnapshots.buildRoundChangesCommand(workDir, from, to), 30000));
+                if (!listed.files.some(file => file.path === filePath)) {
+                    sendJson(res, 404, { error: '该文件不在这一轮的改动里' });
+                    return;
+                }
+                const out = await runWebContainerScript(ctx, sessionRef.containerName, webSnapshots.buildRoundDiffCommand(workDir, from, to, filePath), 30000);
+                sendJson(res, 200, { path: filePath, ...webSnapshots.parseRoundDiffOutput(out) });
+            }
+        },
+        {
+            // 回退前预览：会改 / 删 / 恢复哪些文件（会先拍一张“现在”的快照，不改任何文件）
+            method: 'POST',
+            match: currentPath => currentPath.match(/^\/api\/sessions\/([^/]+)\/rewind\/preview$/),
+            handler: async match => {
+                const sessionRef = getValidSessionRef(ctx, res, match[1]);
+                if (!sessionRef) {
+                    return;
+                }
+                const payload = await readJsonBody(req);
+                const target = findWebRewindTarget(state, sessionRef, payload.messageId);
+                if (target.error) {
+                    sendJson(res, target.status, { error: target.error });
+                    return;
+                }
+                const program = getAgentRuntimeMeta(resolveEffectiveAgentPromptCommandForSession(
+                    target.history, sessionRef.agentId, (listWebManyoyoContainers(ctx)[sessionRef.containerName] || {}).defaultCommand
+                )).agentProgram;
+                const result = { agentProgram: program, precise: program === 'claude', files: null };
+                if (webSnapshots.isSnapId(target.message.snapBefore)) {
+                    const out = await runWebContainerScript(ctx, sessionRef.containerName, webSnapshots.buildRestorePreviewCommand(resolveWebSessionWorkDir(state, sessionRef), target.message.snapBefore), 30000);
+                    const preview = webSnapshots.parseRestorePreviewOutput(out);
+                    result.files = preview.ok ? preview : { ok: false, reason: preview.reason };
+                }
+                sendJson(res, 200, result);
+            }
+        },
+        {
+            // 回退：scope = both（对话和文件）/ conversation（只对话）/ files（只文件）
+            method: 'POST',
+            match: currentPath => currentPath.match(/^\/api\/sessions\/([^/]+)\/rewind$/),
+            handler: async match => {
+                const sessionRef = getValidSessionRef(ctx, res, match[1]);
+                if (!sessionRef) {
+                    return;
+                }
+                const payload = await readJsonBody(req);
+                const scope = String(payload.scope || '');
+                if (!['both', 'conversation', 'files'].includes(scope)) {
+                    sendJson(res, 400, { error: 'scope 只能是 both、conversation 或 files' });
+                    return;
+                }
+                const outcome = await rewindWebSession(ctx, state, sessionRef, payload.messageId, scope);
+                if (outcome.error) {
+                    sendJson(res, outcome.status, { error: outcome.error });
+                    return;
+                }
+                sendJson(res, 200, outcome);
+            }
+        },
+        {
+            method: 'POST',
+            match: currentPath => currentPath.match(/^\/api\/sessions\/([^/]+)\/messages\/hide$/),
+            handler: async match => {
+                const sessionRef = getValidSessionRef(ctx, res, match[1]);
+                if (!sessionRef) {
+                    return;
+                }
+                const payload = await readJsonBody(req);
+                if (state.agentRuns.has(sessionRef.containerName)) {
+                    sendJson(res, 409, { error: '任务进行中，暂时不能隐藏' });
+                    return;
+                }
+                const changed = setWebSessionTurnHidden(state.webHistoryDir, sessionRef, String(payload.messageId || ''), payload.hidden !== false);
+                if (!changed) {
+                    sendJson(res, 404, { error: '没有找到这一组' });
+                    return;
+                }
+                sendJson(res, 200, { ok: true, count: changed });
+            }
+        },
         {
             // “改动”视图：工作目录所在 git 仓库的改动列表（按需请求，前端不轮询）
             method: 'GET',
@@ -7642,6 +8341,13 @@ async function handleWebApi(req, res, pathname, ctx, state) {
                 }
 
                 const payload = await readJsonBody(req);
+                let streamImages;
+                try {
+                    streamImages = webUploads.parseImages(payload.images);
+                } catch (e) {
+                    sendJson(res, 400, { error: e.message });
+                    return;
+                }
                 const prompt = (payload.prompt || '').trim();
                 if (!prompt) {
                     sendJson(res, 400, { error: 'prompt 不能为空' });
@@ -7654,7 +8360,7 @@ async function handleWebApi(req, res, pathname, ctx, state) {
                 if (rejectDuplicateClientMessage(res, state.webHistoryDir, sessionRef, streamClientId.value, { includeQueue: true })) {
                     return;
                 }
-                const turn = await runWebAgentStreamTurn(ctx, state, sessionRef, prompt, streamClientId.value, res);
+                const turn = await runWebAgentStreamTurn(ctx, state, sessionRef, prompt, streamClientId.value, res, streamImages);
                 if (turn.busy) {
                     sendJson(res, 409, { error: '当前容器已有运行中的 agent 任务，请等它结束或先停止' });
                 } else if (turn.error) {
@@ -7671,6 +8377,13 @@ async function handleWebApi(req, res, pathname, ctx, state) {
                     return;
                 }
                 const payload = await readJsonBody(req);
+                let queueImages;
+                try {
+                    queueImages = webUploads.parseImages(payload.images);
+                } catch (e) {
+                    sendJson(res, 400, { error: e.message });
+                    return;
+                }
                 const text = (payload.prompt || '').trim();
                 if (!text) {
                     sendJson(res, 400, { error: 'prompt 不能为空' });
@@ -7696,7 +8409,7 @@ async function handleWebApi(req, res, pathname, ctx, state) {
                 // 入队与下面的调度之间没有 await：队列落盘和打断判断对同一会话是原子的
                 const history = loadWebSessionHistory(state.webHistoryDir, sessionRef.containerName);
                 const agentSession = getWebAgentSession(history, sessionRef.agentId, { create: true, includeArchived: true });
-                const added = agentQueue.enqueue(agentSession, { clientMessageId: queueClientId.value, text, when });
+                const added = agentQueue.enqueue(agentSession, { clientMessageId: queueClientId.value, text, when, images: queueImages });
                 if (!added.ok) {
                     sendJson(res, 409, { error: '排队已满（最多 10 条），请先取消几条或等它们发出', full: true });
                     return;
@@ -7975,6 +8688,7 @@ async function startWebServer(options) {
             ? options.agentRawOutputMaxChars
             : AGENT_RAW_OUTPUT_MAX_CHARS,
         // 追加提示词“当前步骤结束后插入”等不到步骤边界时，退化成立即打断的等待时间
+        orphanPollMs: Number.isFinite(options.orphanPollMs) && options.orphanPollMs > 0 ? options.orphanPollMs : WEB_ORPHAN_POLL_MS,
         agentStepFallbackMs: Number.isFinite(options.agentStepFallbackMs) && options.agentStepFallbackMs > 0
             ? options.agentStepFallbackMs
             : agentQueue.STEP_FALLBACK_MS,
@@ -7993,7 +8707,15 @@ async function startWebServer(options) {
     const state = {
         webHistoryDir: options.webHistoryDir || path.join(os.homedir(), '.manyoyo', 'web-history'),
         webConfigPath: options.webConfigPath || getDefaultWebConfigPath(),
-        authSessions: new Map(),
+        orphanTimers: new Set(),
+        authStore: createAuthStore({
+            file: options.authSessionsFile || '',
+            user: ctx.authUser,
+            pass: ctx.authPass,
+            ttlMs: WEB_AUTH_TTL_SECONDS * 1000,
+            now: Date.now,
+            warn: message => ctx.logger.warn(message)
+        }),
         terminalSessions: new Map(),
         agentRuns: new Map(),
         // imageRef -> { status: 'pulling'|'failed', message, promise }
@@ -8206,6 +8928,7 @@ async function startWebServer(options) {
     });
 
     startStaleSetupCleanup(ctx);
+    state.orphanReconcileReady = reconcileOrphanTurns(ctx, state).catch(e => ctx.logger.warn('orphan reconcile failed', { message: e && e.message }));
     startContainerNetworkWatch(ctx, state);
     if (ctx.autoPullImage) {
         startWebImagePrepare(ctx, state);
@@ -8219,6 +8942,9 @@ async function startWebServer(options) {
         close: () => new Promise(resolve => {
             ctx.logger.info('web server closing');
             flushWebSessionHistories();
+            state.authStore.close();
+            state.orphanTimers.forEach(timer => clearInterval(timer));
+            state.orphanTimers.clear();
             if (state.networkWatch) {
                 state.networkWatch.stop();
                 state.networkWatch = null;