@xiaobuyu/nodesign 0.0.6 → 0.0.8

package/server/api/sessions-rewind.js

@@ -0,0 +1,220 @@
+/**
+ * server/api/sessions-rewind.js — 「回到某条消息之前」（2026-08-30 从 sessions.js
+ * 拆出，行数棘轮）。
+ *
+ * 它自成一件事：两个正交开关（回不回文件 / 截不截对话）× 三条执行路径（不碰 SDK /
+ * 用活口 query / 起临时 query），加上 jsonl 截断那套原子写。放回 sessions.js 会让
+ * 那个文件一半篇幅在讲回滚。
+ *
+ * `pendingRewinds` 也跟着搬过来 —— 它是这套流程的互斥牌，turn.js 拿它拒同 sid 新
+ * turn（防两个 SDK subprocess 同时写一份 jsonl，或 turn 写进正要被砍掉的那段尾巴）。
+ */
+
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { guardProject } from './_guard.js';
+import { closeQuerySession, hasActiveQuerySession, getQuerySession } from '../engine/runs/active-runs.js';
+import { getSessionWorkspace, validateSessionId } from '../projects/workspace.js';
+import { jsonlExistsForSession, truncateJsonlAtMessage } from '../projects/session-jsonl.js';
+import { AsyncQueue } from '../lib/async-queue.js';
+import { getProjectBus } from '../ws/broker.js';
+import { platform } from '../runtime/platform.js';
+
+const GLOBAL_CLAUDE_CONFIG_DIR = platform.claudeConfigDir;
+
+/**
+ * 进行中的 rewind 操作 sid 集合 —— 供 turn.js startNewRunSession 守卫使用，
+ * 防止同 sid 临时 rewind query 跟 normal turn query 同时启动撞 jsonl。
+ */
+export const pendingRewinds = new Set();
+
+/** 把 rewind 路由挂到 sessions 的 router 上（sessions.js 调一次）。 */
+export function mountRewindRoute(router) {
+  // ── POST /:pid/sessions/:sid/rewind ──
+  // 回到某条用户消息之前。**两件事，两个开关，互相正交**（2026-08-30 拆开）：
+  //
+  //   files=true           产物回退：SDK Query.rewindFiles(userMessageId) 把工作区文件
+  //                        回滚到该消息之前（后续 Edit/Write 全撤销）。SDK file
+  //                        checkpoint 写在 session jsonl（type='file-history-snapshot'），
+  //                        跨进程持久化天然搞定。
+  //   truncateConversation 对话回退：把 jsonl 截到该消息之前。显示与模型记忆读的都是
+  //   =true                这份 jsonl，所以截了记忆才真的回退。
+  //
+  // 以前这两件绑死一起做。拆开是因为它们是两种不同的后悔：「这句话我说错了，重说」
+  // 只该动对话；「它照我说的做出来的东西我不要了」才该动文件。默认值仍是两个都 true
+  // ——「回到此处」的老行为一字不改。
+  //
+  // ⚠️ 产物只有一份（一个项目一个工作区），所以 files=true 是**项目级**的影响：
+  // 同项目其他会话看到的也是回退后的文件。调用方要在 UI 上把这件事说明白。
+  //
+  // 三条路径：
+  //   0. files=false → 压根不需要 SDK（关活口 query + 截 jsonl 即可），瞬间完成
+  //   1. active query 在跑 → 直接用现有 query.rewindFiles（最快，无 spawn 成本）
+  //   2. session 已 close（历史 session）→ 起临时 query (resume + drain) → rewindFiles → close
+  //
+  // 历史 session 也能 undo —— 之前返 410 是应用层偷懒，SDK 完全支持 resume + rewindFiles。
+  //
+  // body: { userMessageId, files?=true, truncateConversation?=true }
+  // 200 { canRewind, filesChanged?, insertions?, deletions?, conversationTruncated, removedEntries }
+  // 400 两个开关都 false（没让它做任何事）
+  // 404 { code: 'JSONL_MISSING' }   jsonl 不存在（session 删了 / 部分创建）
+  // 409 { code: 'REWIND_BUSY' }     同 sid 已有 rewind 进行中
+  // 500 { code: 'REWIND_FAILED' }   临时 query 启动 / rewindFiles 失败
+  router.post('/:pid/sessions/:sid/rewind', async (req, res, next) => {
+    try {
+      validateSessionId(req.params.sid);
+      const project = guardProject(req, res);
+      if (!project) return;
+
+      const { userMessageId, files = true, truncateConversation = true } = req.body || {};
+      if (!userMessageId || typeof userMessageId !== 'string') {
+        return res.status(400).json({ error: 'userMessageId required' });
+      }
+      const wantFiles = files !== false;
+      const wantTruncate = truncateConversation !== false;
+      if (!wantFiles && !wantTruncate) {
+        return res.status(400).json({ error: 'nothing to do: files and truncateConversation both false' });
+      }
+
+      const { pid, sid } = req.params;
+
+      // ── 路径 0：只回对话 ──
+      // 不碰 SDK 就够了：关掉活口 query（下条消息从截断后的 jsonl resume，记忆才真的
+      // 回退），等它 flush 完把 jsonl 截了。省掉临时 query 那 3-5 秒的 spawn。
+      if (!wantFiles) {
+        const sessionRoot = getSessionWorkspace(pid, sid);
+        if (!await jsonlExistsForSession(sessionRoot, sid)) {
+          return res.status(404).json({ error: 'session jsonl not found', code: 'JSONL_MISSING' });
+        }
+        if (pendingRewinds.has(sid)) {
+          return res.status(409).json({ error: 'rewind in progress', code: 'REWIND_BUSY' });
+        }
+        // 挂牌同 SDK 路径：turn.js 见 pendingRewinds 有这个 sid 就拒新 turn。这条路
+        // 虽然不起临时 query，但它**写** jsonl —— 截断中途来一条 turn 会写进正要被
+        // 砍掉的那段尾巴上。
+        pendingRewinds.add(sid);
+        try {
+          if (hasActiveQuerySession(sid)) {
+            try { closeQuerySession(sid, 'rewind_truncate'); } catch { /* */ }
+            await new Promise((r) => setTimeout(r, 800));
+          }
+          const removed = await truncateJsonlAtMessage(sessionRoot, sid, userMessageId);
+          const payload = { canRewind: removed != null, filesChanged: [], conversationTruncated: removed != null, removedEntries: removed ?? 0 };
+          emitRewindFiles(pid, sid, payload);
+          return res.json(payload);
+        } finally {
+          pendingRewinds.delete(sid);
+        }
+      }
+
+      // 路径 1：active query 在跑 —— 直接用现有 query
+      const rec = getQuerySession(sid);
+      if (rec?.query && !rec.abortController.signal.aborted) {
+        const result = await rec.query.rewindFiles(userMessageId);
+        // 对话层同步回滚（2026-08-08「做完整」）：rewindFiles 只回文件。显示与模型
+        // 记忆读的都是这份 jsonl —— 关掉活口 query（下条消息从截断后的 jsonl resume，
+        // 记忆才真的回退），等 SDK flush 后把 jsonl 截到该 user 消息之前。
+        // truncateConversation=false（fork 带产物回退那条路）时整段跳过：源会话的
+        // 对话要原样留着，动的只有磁盘。query 也不关 —— 不截 jsonl 就没有"让它重读"的必要。
+        let removed = null;
+        if (wantTruncate) {
+          try { closeQuerySession(sid, 'rewind_truncate'); } catch { /* */ }
+          await new Promise((r) => setTimeout(r, 800));
+          removed = await truncateJsonlAtMessage(getSessionWorkspace(pid, sid), sid, userMessageId);
+        }
+        const payload = { ...result, conversationTruncated: removed != null, removedEntries: removed ?? 0 };
+        emitRewindFiles(pid, sid, payload);
+        return res.json(payload);
+      }
+
+      // race guard：active session 存在但 query handle 未 attach（session 启动中
+      // 的窄 race window — registerQuerySession 已 set Map 但 attachSessionQuery
+      // 还没赋值 query 字段）→ 拒 409 让用户重试。如果直接 fallthrough 进路径 2
+      // 起临时 query，两个 SDK binary 会同时 attach 同一 jsonl 文件 → 错乱不可恢复。
+      if (hasActiveQuerySession(sid) && rec && !rec.abortController.signal.aborted) {
+        return res.status(409).json({
+          error: 'session is starting (query handle not yet attached), retry shortly',
+          code: 'SESSION_STARTING',
+        });
+      }
+
+      // 路径 2：起临时 query resume → rewindFiles → close
+      if (pendingRewinds.has(sid)) {
+        return res.status(409).json({ error: 'rewind in progress', code: 'REWIND_BUSY' });
+      }
+      const sessionRoot = getSessionWorkspace(pid, sid);
+      if (!await jsonlExistsForSession(sessionRoot, sid)) {
+        return res.status(404).json({ error: 'session jsonl not found', code: 'JSONL_MISSING' });
+      }
+
+      pendingRewinds.add(sid);
+      const inputQueue = new AsyncQueue();
+      let tempQuery = null;
+      let drain = null;
+      try {
+        tempQuery = query({
+          prompt: inputQueue,
+          options: {
+            resume: sid,
+            enableFileCheckpointing: true,
+            cwd: sessionRoot,
+            // 关键：跟 runSession 一致传 CLAUDE_CONFIG_DIR，否则 SDK 找不到 jsonl
+            env: { ...process.env, CLAUDE_CONFIG_DIR: GLOBAL_CLAUDE_CONFIG_DIR },
+            persistSession: true,
+            // 不传 hooks / mcpServers / agents / canUseTool —— 临时 query 不跑 turn
+          },
+        });
+        // fire-and-forget consume —— SDK control method 走 bidirectional protocol，
+        // stream 不消费会卡死 control RPC。drain 跑在后台，close 后自然结束。
+        drain = (async () => {
+          try { for await (const _ of tempQuery) { /* discard */ } }
+          catch { /* expected on close */ }
+        })();
+        // 15s timeout（SDK boot + jsonl load + control RPC ~3-5s 正常 → 3× margin）
+        const result = await Promise.race([
+          tempQuery.rewindFiles(userMessageId),
+          new Promise((_, rj) => setTimeout(() => rj(new Error('rewind timeout')), 15000)),
+        ]);
+        // 对话层回滚：先收干净临时 query（文件句柄/尾部 flush），再截断 jsonl
+        try { tempQuery.close(); } catch { /* */ }
+        try { inputQueue.close(); } catch { /* */ }
+        if (drain) { try { await drain; } catch { /* */ } }
+        tempQuery = null; drain = null;
+        let removed = null;
+        if (wantTruncate) {
+          await new Promise((r) => setTimeout(r, 300));
+          removed = await truncateJsonlAtMessage(sessionRoot, sid, userMessageId);
+        }
+        const payload = { ...result, conversationTruncated: removed != null, removedEntries: removed ?? 0 };
+        emitRewindFiles(pid, sid, payload);
+        res.json(payload);
+      } catch (err) {
+        console.warn(`[sessions.rewind] temp query failed (sid=${sid.slice(0, 8)}): ${err.message}`);
+        res.status(500).json({ error: err.message, code: 'REWIND_FAILED' });
+      } finally {
+        try { tempQuery?.close(); } catch { /* ignore */ }
+        try { inputQueue.close(); } catch { /* ignore */ }
+        if (drain) { try { await drain; } catch { /* ignore */ } }
+        pendingRewinds.delete(sid);
+      }
+    } catch (err) { next(err); }
+  });
+}
+
+/**
+ * rewindFiles 成功后 emit run.file_changed 事件让前端 iframe 自动 reload。
+ * 复用现有 event 类型 —— ProjectWorkspace.jsx 已 case 它（仅 .html 后缀 bump reloadToken），
+ * 0 前端事件代码改动。
+ */
+function emitRewindFiles(pid, sid, result) {
+  if (!result?.canRewind || !Array.isArray(result.filesChanged) || !result.filesChanged.length) return;
+  const bus = getProjectBus(pid);
+  for (const filePath of result.filesChanged) {
+    bus.publish({
+      type: 'run.file_changed',
+      filePath,
+      event: 'change',
+      sessionId: sid,
+      ts: new Date().toISOString(),
+    });
+  }
+}

package/server/api/sessions.js

@@ -22,7 +22,6 @@ import {
   renameSession,
   tagSession,
   deleteSession,
-  query,
 } from '@anthropic-ai/claude-agent-sdk';
 import { validateProjectId, getProject, setActiveSession } from '../projects/store.js';
 import { guardProject, modelUserFor } from './_guard.js';
@@ -41,21 +40,21 @@ import {
 import { withConfigDir } from '../lib/sdk-session.js';
 import { patchBoard } from '../projects/board-store.js';
 import { platform } from '../runtime/platform.js';
-import { AsyncQueue } from '../lib/async-queue.js';
 import { getProjectBus } from '../ws/broker.js';
 import { getLastContextUsage } from '../engine/runs/live-turn.js';
 import { Events } from '../engine/agent/events.js';
-import { resolveSessionModel, applySessionModel } from '../engine/agent/session-model.js';
-import { selectableModelsFor, allowedModelsFor, isModelLockedFor, defaultModelFor, crossLaneSwitchReason } from '../engine/agent/model-context.js';
+import { resolveSessionModel, applySessionModel, defaultModel } from '../engine/agent/session-model.js';
+import { selectableModelsFor, allowedModelsFor, isModelLockedFor, defaultModelFor, modelSwitchRejection } from '../engine/agent/model-context.js';
 
-/**
- * 进行中的 rewind 操作 sid 集合 —— 供 turn.js startNewRunSession 守卫使用，
- * 防止同 sid 临时 rewind query 跟 normal turn query 同时启动撞 jsonl。
- */
-export const pendingRewinds = new Set();
+
+import { mountRewindRoute } from './sessions-rewind.js';
+import { jsonlExistsForSession, truncateJsonlAtLastUserMessage } from '../projects/session-jsonl.js';
 
 const router = express.Router();
 
+// 「回到某条消息之前」整块住在 sessions-rewind.js（行数棘轮，2026-08-30 拆出）
+mountRewindRoute(router);
+
 // SDK session API 需要 CLAUDE_CONFIG_DIR 指向 JSONL 实际存储的全局目录
 // 来自 runtime/platform.js（跨平台决策单一来源）
 const GLOBAL_CLAUDE_CONFIG_DIR = platform.claudeConfigDir;
@@ -244,12 +243,23 @@ router.put('/:pid/sessions/:sid/model', async (req, res, next) => {
 
     await ensureSessionWorkspace(req.params.pid, req.params.sid);
     const metaDir = getSessionMetaDir(req.params.pid, req.params.sid);
+    // ⛔ 这条闸 08-25 之前是**死守卫**（08-21 装的时候就写错了位置）：它写在 applySessionModel 之后，
+    // 又拿 apply **之后**读回来的 currentModel 去比 —— 那就是 raw 跟它自己比，crossLaneSwitchReason
+    // 的第一行 `fromModel === toModel` 直接返回 null，一次都没拦住过；而且就算能拦，文件已经写了、
+    // 空闲的 query 也已经被 applySessionModel 关掉重启了，409 只是句马后炮。
+    // 现在：**apply 之前**读、拿 apply 之前的有效模型比。`raw === null`（清覆盖回默认）同样要判 ——
+    // 从 Ox 会话清回订阅默认，是同一个病。
+    const before = await resolveSessionModel(metaDir);
+    const target = raw ?? defaultModel();
+    // 只对**跑过的会话**拦：这条闸防的是历史里那些没有 signature 的 thinking 块被回传给真 Anthropic
+    // （08-21 fable P3）。还没跑过的会话没有历史，拦它只会让人换不了模型。
+    const why = modelSwitchRejection({
+      from: before.model, to: target,
+      hasHistory: await jsonlExistsForSession(getSessionWorkspace(req.params.pid, req.params.sid), req.params.sid),
+    });
+    if (why) return res.status(409).json({ error: why, code: 'LANE_SWITCH' });
     const result = await applySessionModel(req.params.sid, metaDir, raw, 'picker');
-    const { fallback, model: currentModel } = await resolveSessionModel(metaDir);
-    if (raw !== null) {
-      const why = crossLaneSwitchReason(currentModel, raw);
-      if (why) return res.status(409).json({ error: why, code: 'LANE_SWITCH' });
-    }
+    const { fallback } = await resolveSessionModel(metaDir);
     res.json({
       model: result.model,
       override: result.override,
@@ -272,9 +282,25 @@ router.post('/:pid/sessions/:sid/fork', async (req, res, next) => {
     const srcSessionRoot = getSessionWorkspace(req.params.pid, srcSid);
     const { upToMessageId, title } = req.body || {};
 
+    // 标题：不传就自己拼一个（08-30）。SDK 会把源会话的标题原样复制过来，于是
+    // 会话列表里两条同名，用户分不出哪条是刚分出来的。带 upToMessageId 的入口
+    // （气泡上的「从这里分叉」）拿不到标题也不该为它穿三层 props，所以在这拼。
+    let finalTitle = title;
+    if (!finalTitle && upToMessageId) {
+      const srcInfo = await withConfigDir(GLOBAL_CLAUDE_CONFIG_DIR, () =>
+        getSessionInfo(srcSid, { dir: srcSessionRoot }),
+      ).catch(() => null);
+      const base = srcInfo?.customTitle || srcInfo?.summary || '';
+      finalTitle = base ? `${base} · 分支` : '分支';
+    }
+
     // 1. SDK fork —— 在 GLOBAL_CLAUDE_CONFIG_DIR 下生成新 sid 的 jsonl
+    //
+    // ⚠️ 带 upToMessageId 时**不在这里设标题**：下面第 4 步的补刀是前缀截断，而
+    // forkSession 写的 custom-title 行排在最后那条用户消息之后，会被一起砍掉
+    // （探针实测：9 行 fork 补刀删 3 行，标题那行在里面）。所以补完刀再设。
     const result = await withConfigDir(GLOBAL_CLAUDE_CONFIG_DIR, () =>
-      forkSession(srcSid, { dir: srcSessionRoot, upToMessageId, title }),
+      forkSession(srcSid, { dir: srcSessionRoot, upToMessageId, title: upToMessageId ? undefined : finalTitle }),
     );
     const newSid = result.sessionId;
     validateSessionId(newSid);
@@ -315,6 +341,23 @@ router.post('/:pid/sessions/:sid/fork', async (req, res, next) => {
       }
     }
 
+    // 4. 「到这条为止」在我们这儿是**不含**那条（08-30）。
+    //
+    // SDK 的 upToMessageId 是含的（探针实测），而这个接口的调用方是「从这条消息
+    // 分叉」—— 用户点的是自己那句想重说的话，含着它 fork 出来等于什么都没改。
+    // uuid 被 fork 重映射过，拿原 id 截不到，所以按"最后一条真用户消息"下刀。
+    // 不传 upToMessageId 的整条 fork（会话列表那个入口）不受影响。
+    if (upToMessageId) {
+      await truncateJsonlAtLastUserMessage(newSessionRoot, newSid);
+      // 标题在补刀之后才落得住（见上）。设不上不算失败 —— 分支本身已经好了，
+      // 列表里退回摘要显示而已。
+      if (finalTitle) {
+        await withConfigDir(GLOBAL_CLAUDE_CONFIG_DIR, () =>
+          renameSession(newSid, finalTitle, { dir: newSessionRoot }),
+        ).catch((err) => console.warn(`[fork] 设分支标题失败：${err.message}`));
+      }
+    }
+
     res.json({ sessionId: newSid });
   } catch (err) { next(err); }
 });
@@ -407,183 +450,4 @@ router.delete('/:pid/sessions/:sid', async (req, res, next) => {
 });
 
 
-// ── POST /:pid/sessions/:sid/rewind ──
-// SDK Query.rewindFiles(userMessageId) 控制方法 —— 把 session 内文件回滚到该
-// user message 之前的状态（后续 Edit/Write 全撤销）。SDK file checkpoint 写在
-// session jsonl（type='file-history-snapshot'），跨进程持久化天然搞定。
-//
-// 两条路径：
-//   1. active query 在跑 → 直接用现有 query.rewindFiles（最快，无 spawn 成本）
-//   2. session 已 close（历史 session）→ 起临时 query (resume + drain) → rewindFiles → close
-//
-// 历史 session 也能 undo —— 之前返 410 是应用层偷懒，SDK 完全支持 resume + rewindFiles。
-//
-// body: { userMessageId }
-// 200 { canRewind, filesChanged?, insertions?, deletions? }
-// 404 { code: 'JSONL_MISSING' }   jsonl 不存在（session 删了 / 部分创建）
-// 409 { code: 'REWIND_BUSY' }     同 sid 已有 rewind 进行中
-// 500 { code: 'REWIND_FAILED' }   临时 query 启动 / rewindFiles 失败
-router.post('/:pid/sessions/:sid/rewind', async (req, res, next) => {
-  try {
-    validateSessionId(req.params.sid);
-    const project = guardProject(req, res);
-    if (!project) return;
-
-    const { userMessageId } = req.body || {};
-    if (!userMessageId || typeof userMessageId !== 'string') {
-      return res.status(400).json({ error: 'userMessageId required' });
-    }
-
-    const { pid, sid } = req.params;
-
-    // 路径 1：active query 在跑 —— 直接用现有 query
-    const rec = getQuerySession(sid);
-    if (rec?.query && !rec.abortController.signal.aborted) {
-      const result = await rec.query.rewindFiles(userMessageId);
-      // 对话层同步回滚（2026-08-08「做完整」）：rewindFiles 只回文件。显示与模型
-      // 记忆读的都是这份 jsonl —— 关掉活口 query（下条消息从截断后的 jsonl resume，
-      // 记忆才真的回退），等 SDK flush 后把 jsonl 截到该 user 消息之前。
-      try { closeQuerySession(sid, 'rewind_truncate'); } catch { /* */ }
-      await new Promise((r) => setTimeout(r, 800));
-      const removed = await truncateJsonlAtMessage(getSessionWorkspace(pid, sid), sid, userMessageId);
-      const payload = { ...result, conversationTruncated: removed != null, removedEntries: removed ?? 0 };
-      emitRewindFiles(pid, sid, payload);
-      return res.json(payload);
-    }
-
-    // race guard：active session 存在但 query handle 未 attach（session 启动中
-    // 的窄 race window — registerQuerySession 已 set Map 但 attachSessionQuery
-    // 还没赋值 query 字段）→ 拒 409 让用户重试。如果直接 fallthrough 进路径 2
-    // 起临时 query，两个 SDK binary 会同时 attach 同一 jsonl 文件 → 错乱不可恢复。
-    if (hasActiveQuerySession(sid) && rec && !rec.abortController.signal.aborted) {
-      return res.status(409).json({
-        error: 'session is starting (query handle not yet attached), retry shortly',
-        code: 'SESSION_STARTING',
-      });
-    }
-
-    // 路径 2：起临时 query resume → rewindFiles → close
-    if (pendingRewinds.has(sid)) {
-      return res.status(409).json({ error: 'rewind in progress', code: 'REWIND_BUSY' });
-    }
-    const sessionRoot = getSessionWorkspace(pid, sid);
-    if (!await jsonlExistsForSession(sessionRoot, sid)) {
-      return res.status(404).json({ error: 'session jsonl not found', code: 'JSONL_MISSING' });
-    }
-
-    pendingRewinds.add(sid);
-    const inputQueue = new AsyncQueue();
-    let tempQuery = null;
-    let drain = null;
-    try {
-      tempQuery = query({
-        prompt: inputQueue,
-        options: {
-          resume: sid,
-          enableFileCheckpointing: true,
-          cwd: sessionRoot,
-          // 关键：跟 runSession 一致传 CLAUDE_CONFIG_DIR，否则 SDK 找不到 jsonl
-          env: { ...process.env, CLAUDE_CONFIG_DIR: GLOBAL_CLAUDE_CONFIG_DIR },
-          persistSession: true,
-          // 不传 hooks / mcpServers / agents / canUseTool —— 临时 query 不跑 turn
-        },
-      });
-      // fire-and-forget consume —— SDK control method 走 bidirectional protocol，
-      // stream 不消费会卡死 control RPC。drain 跑在后台，close 后自然结束。
-      drain = (async () => {
-        try { for await (const _ of tempQuery) { /* discard */ } }
-        catch { /* expected on close */ }
-      })();
-      // 15s timeout（SDK boot + jsonl load + control RPC ~3-5s 正常 → 3× margin）
-      const result = await Promise.race([
-        tempQuery.rewindFiles(userMessageId),
-        new Promise((_, rj) => setTimeout(() => rj(new Error('rewind timeout')), 15000)),
-      ]);
-      // 对话层回滚：先收干净临时 query（文件句柄/尾部 flush），再截断 jsonl
-      try { tempQuery.close(); } catch { /* */ }
-      try { inputQueue.close(); } catch { /* */ }
-      if (drain) { try { await drain; } catch { /* */ } }
-      tempQuery = null; drain = null;
-      await new Promise((r) => setTimeout(r, 300));
-      const removed = await truncateJsonlAtMessage(sessionRoot, sid, userMessageId);
-      const payload = { ...result, conversationTruncated: removed != null, removedEntries: removed ?? 0 };
-      emitRewindFiles(pid, sid, payload);
-      res.json(payload);
-    } catch (err) {
-      console.warn(`[sessions.rewind] temp query failed (sid=${sid.slice(0, 8)}): ${err.message}`);
-      res.status(500).json({ error: err.message, code: 'REWIND_FAILED' });
-    } finally {
-      try { tempQuery?.close(); } catch { /* ignore */ }
-      try { inputQueue.close(); } catch { /* ignore */ }
-      if (drain) { try { await drain; } catch { /* ignore */ } }
-      pendingRewinds.delete(sid);
-    }
-  } catch (err) { next(err); }
-});
-
-/**
- * 检查 SDK jsonl 是否存在 —— 历史 session 在 ~/.claude/projects/<encoded-cwd>/<sid>.jsonl。
- * encodeCwdForSDK + GLOBAL_CLAUDE_CONFIG_DIR 都已在文件顶部定义。
- */
-/**
- * 对话层回滚（2026-08-08）：把 jsonl 截断到 userMessageId 那条之前（含它与其后全部）。
- * jsonl 是追加式日志，截到 prefix = 它历史上真实存在过的状态，resume 天然自洽；
- * 之后的 file-history-snapshot 属于被撤销的编辑，一并丢弃是正确语义。
- * 原子写（tmp+rename）。找不到该 uuid 返 null（fail-soft：文件回滚仍算成功）。
- */
-async function truncateJsonlAtMessage(sessionRoot, sid, userMessageId) {
-  const jsonlPath = path.join(GLOBAL_CLAUDE_CONFIG_DIR, 'projects', encodeCwdForSDK(sessionRoot), `${sid}.jsonl`);
-  try {
-    const raw = await fs.readFile(jsonlPath, 'utf8');
-    const lines = raw.split('\n');
-    let cut = -1;
-    for (let i = 0; i < lines.length; i++) {
-      if (!lines[i] || !lines[i].includes(userMessageId)) continue;
-      try { if (JSON.parse(lines[i]).uuid === userMessageId) { cut = i; break; } } catch { /* 非 JSON 行跳过 */ }
-    }
-    if (cut < 0) {
-      console.warn(`[sessions.rewind] uuid ${userMessageId.slice(0, 8)} 不在 jsonl 里，跳过对话截断`);
-      return null;
-    }
-    const kept = lines.slice(0, cut).join('\n');
-    const tmp = `${jsonlPath}.tmp-rewind`;
-    await fs.writeFile(tmp, kept ? `${kept}\n` : '');
-    await fs.rename(tmp, jsonlPath);
-    return lines.filter(Boolean).length - lines.slice(0, cut).filter(Boolean).length;
-  } catch (err) {
-    console.warn(`[sessions.rewind] jsonl 截断失败（不影响文件回滚）：${err.message}`);
-    return null;
-  }
-}
-
-async function jsonlExistsForSession(sessionRoot, sid) {
-  const encoded = encodeCwdForSDK(sessionRoot);
-  const jsonlPath = path.join(GLOBAL_CLAUDE_CONFIG_DIR, 'projects', encoded, `${sid}.jsonl`);
-  try {
-    await fs.access(jsonlPath);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * rewindFiles 成功后 emit run.file_changed 事件让前端 iframe 自动 reload。
- * 复用现有 event 类型 —— ProjectWorkspace.jsx 已 case 它（仅 .html 后缀 bump reloadToken），
- * 0 前端事件代码改动。
- */
-function emitRewindFiles(pid, sid, result) {
-  if (!result?.canRewind || !Array.isArray(result.filesChanged) || !result.filesChanged.length) return;
-  const bus = getProjectBus(pid);
-  for (const filePath of result.filesChanged) {
-    bus.publish({
-      type: 'run.file_changed',
-      filePath,
-      event: 'change',
-      sessionId: sid,
-      ts: new Date().toISOString(),
-    });
-  }
-}
-
 export default router;

package/server/api/stage.js

@@ -0,0 +1,35 @@
+/**
+ * server/api/stage.js —— 用户在画布上对角色说话时，把这句话落在画布上（2026-08-29）
+ *
+ * 前身是 api/roles.js（名册 + 直投角色的收件箱）。收件箱 08-29 整族退役：角色不再
+ * 挂着等人说话，用户的话一律经主持人转交（它本来就要在这一拍写场面、排下一步）。
+ * 剩下的这一件事跟收件箱无关，是**画布对话的完整性** —— 用户从画布说的话得在画布上
+ * 留下痕迹，否则那条对话线上只有角色单方面的半边声道。
+ *
+ * 落痕先于转交：前端拿到这条的 rel 之后再把话发给主持人，主持人接得上线。
+ */
+
+import express from 'express';
+import { guardProject } from './_guard.js';
+import { echoUserChalk } from '../engine/runs/user-chalk-echo.js';
+import { getProjectBus } from '../ws/broker.js';
+
+const router = express.Router();
+
+router.post('/:pid/stage/echo', express.json({ limit: '64kb' }), async (req, res, next) => {
+  try {
+    if (!guardProject(req, res)) return;
+    const text = String(req.body?.text || '').trim();
+    if (!text) return res.status(400).json({ error: 'text required' });
+    if (text.length > 8000) return res.status(400).json({ error: 'text too long' });
+    const anchor = typeof req.body?.anchor === 'string' ? req.body.anchor : null;
+
+    const e = await echoUserChalk(req.params.pid, { text, anchor });
+    if (e.seated) {
+      getProjectBus(req.params.pid).publish({ type: 'board.updated', sessionId: null, summary: '你的话落在板上了' });
+    }
+    res.json({ ok: true, echo: e.rel });
+  } catch (err) { next(err); }
+});
+
+export default router;

package/server/api/turn-model-switch.js

@@ -0,0 +1,109 @@
+import { guardProject, guardRunInProject, modelUserFor } from './_guard.js';
+import { getQuery, getRun, getSessionIdByRunId } from '../engine/runs/active-runs.js';
+import { ensureSessionWorkspace, getSessionMetaDir } from '../projects/workspace.js';
+import { applySessionModel, resolveSessionModel, defaultModel } from '../engine/agent/session-model.js';
+import { registerIngressSession } from '../lib/model-ingress.js';
+import { allowedModelsFor, isModelLockedFor, resolveSdkSpoofModel, modelSwitchRejection, resolveModelRoute } from '../engine/agent/model-context.js';
+import { msg } from '../shared/messages.js';
+
+/**
+ * server/api/turn-model-switch.js — 运行中热切模型（08-25 从 turn.js 拆出，那边顶在 600 行棘轮上）。
+ *
+ * 只有这一个端点，但它自己就是一件完整的事：**turn 跑到一半换模型**，而 env（网关地址、钥匙）
+ * 在起 query 那一刻就定死了、SDK 的 setModel 改不动 —— 所以这里的闸比"选模型"那两条路多两道，
+ * 见 model-context.js 的 crossLaneSwitchReason（协议）与 hotSwitchLaneReason（通路）。
+ */
+/**
+ * POST /api/projects/:pid/runs/:runId/model
+ *
+ * 运行中切 model（SDK query.setModel，当场对下一次 LLM 调用生效）。
+ *
+ * **目前只有 API 能到这里**：前端 picker 在 turn 运行中是禁用的，它走
+ * PUT /sessions/:sid/model（那条等空闲才重启 query）。这条留着是因为"turn 跑到
+ * 一半换模型"是它独有的能力，PUT 那条按设计做不到。前端那个没人调的 Turn.setModel
+ * 绑定已删（doc 里还写着 kimi 时代的 model 名，留着只会误导下一个人）。
+ *
+ * 2026-07-30：切完**必须同时落 session-config**。原来这条只改运行时不写文件，
+ * 于是"当前这轮是 Opus、下次 resume 变回 Sonnet"，而且界面无从得知；跟另外两条
+ * 写模型的路加起来，同一个事实有三个互不知情的写者。现在统一走 applySessionModel，
+ * 它自己会判断要不要重启空闲 query（这里 query 正在跑，不会重启）。
+ *
+ * Body: { model: string | null }  - null = 清掉覆盖回到全局默认
+ */
+export async function hotSwitchModelHandler(req, res, next) {
+  try {
+    const project = guardProject(req, res);
+    if (!project) return;
+    if (!guardRunInProject(req, res)) return;
+
+    const { runId } = req.params;
+    const { model } = req.body || {};
+    if (model !== null && model !== undefined && typeof model !== 'string') {
+      return res.status(400).json({ error: 'model must be string or null' });
+    }
+
+    // ⭐ 清覆盖（model=null）也要按"切到全局默认那一行"来判、来切。以前这条直接 setModel(undefined)：
+    // API 会话里等于让 SDK 用它自己的默认 Claude 名发请求，入口反查不到就兜底到本会话的 **helper 行** ——
+    // 表现是"点了『默认』，这一轮偷偷降级成 helper 模型"，而落盘写的是全局默认，运行时和文件对不上。
+    const wanted = typeof model === 'string' ? model.trim() : '';
+    const target = wanted || defaultModel();
+
+    // 08-21：热切路以前不过白名单（任意字符串直达 SDK）。与 PUT /sessions/:sid/model 同口径
+    if (wanted) {
+      const modelUser = modelUserFor(req, project);   // 资格按项目 owner 算（_guard.js）
+      if (isModelLockedFor(modelUser, wanted)) {
+        return res.status(403).json({ error: msg(req, '这个模型仅限 Pro 档，暂未对外开放'), code: 'MODEL_LOCKED', model: wanted });
+      }
+      if (!allowedModelsFor(modelUser).some((m) => m.id === wanted)) {
+        return res.status(400).json({ error: `unknown model: ${model}`, code: 'UNKNOWN_MODEL' });
+      }
+    }
+    const sidForLane = getSessionIdByRunId(runId);
+    if (sidForLane) {
+      const cur = await resolveSessionModel(getSessionMetaDir(project.id, sidForLane));
+      // running:true = 除了协议闸还要过通路闸（env 在起 query 那一刻定死，跨通路热切会拿订阅额度去跑 API 模型）。
+      // 这里的会话必然跑过（getQuery 拿得到活的 run），hasHistory 用默认的 true
+      const why = modelSwitchRejection({ from: cur.model, to: target, running: true });
+      if (why) return res.status(409).json({ error: why, code: 'LANE_SWITCH' });
+    }
+
+    const query = getQuery(runId);
+    if (!query) {
+      return res.status(404).json({
+        error: 'run not active',
+        code: 'RUN_NOT_ACTIVE',
+      });
+    }
+    if (typeof query.setModel !== 'function') {
+      return res.status(501).json({
+        error: 'SDK query handle missing setModel method',
+        code: 'METHOD_NOT_AVAILABLE',
+      });
+    }
+
+    const sid = getSessionIdByRunId(runId);
+    // API 行喂 SDK 的是 spoof 名（session-loop 同款），appModel 本身 binary 不认识
+    await query.setModel(resolveSdkSpoofModel(target));
+    // 运行时切完再落盘：setModel 失败就不该留下"配置说切了"的假象
+    let persisted = null;
+    if (sid) {
+      await ensureSessionWorkspace(project.id, sid);
+      persisted = await applySessionModel(sid, getSessionMetaDir(project.id, sid), model ?? null, 'runtime');
+      // ⭐ 入口的会话路由是**起 query 时**按当时的模型注册的（session-loop.js 的 registerIngressSession），
+      // 热切必须跟着改注册，否则切过去的请求按旧注册判：独占别名算 collision、共用别名算 fallback，
+      // 两种都改道回旧会话的 fast 行 —— 表现是"切了但这一轮没生效"，而且 fallback 每个名字只记一次日志，
+      // 事后连线索都不容易翻到。上面的闸保证了这里两边同通路，所以只可能 api→api。
+      const route = resolveModelRoute(persisted?.model || target);
+      if (route.mode === 'api') {
+        registerIngressSession(sid, route.appModel);
+        // 记账那一侧也得跟着改：AgentContext.appModel 是起 query 时定死的，而 repriceUsageDeltas 按它
+        // 做「会话优先」归属（共用别名根本不在全表反查里，纠不回来）—— 不更新的话热切之后主行那笔账
+        // 会一直记在**切之前**那一行头上。⚠️ 只精确到下一次 absorb：本次差分窗口里切换前后的 usage
+        // 混在一起，会整体归到新行；这比"整轮全记错行"好，但不是零误差。
+        const run = getRun(runId);
+        if (run?.ctx) run.ctx.appModel = route.appModel;
+      }
+    }
+    res.json({ ok: true, model: persisted?.model ?? model, override: persisted?.override ?? null });
+  } catch (err) { next(err); }
+}