@xiaobuyu/nodesign 0.0.1 → 0.0.3

package/server/engine/runs/board-tasklist.js

@@ -0,0 +1,130 @@
+/**
+ * server/engine/runs/board-tasklist.js —— 把 agent 的步骤清单镜像成板书（2026-08-23）
+ *
+ * 用户定的文化：板书是基础设施。agent 开工时用 TodoWrite 列的步骤不该只活在侧栏的计划
+ * 面板里 —— 它是这一轮的骨架，该写在画布上、每一步产出的东西连到对应步骤。
+ * 这件事**由 harness 做，不靠 agent 记得**：
+ *   - run.todo.updated → 一条板书 `notes/板书/<stamp>-步骤.md`（一轮一条、原地更新），
+ *     Markdown 任务列表：✓ 已做 / → 正在（加粗）/ 待做；落定不走 staging
+ *   - run.file_changed（有"正在"的步骤时）→ 这条板书到那件产物的 annotates 线，label「第 N 步」，
+ *     by:'auto'（不算进主角焦点分；同一轮同一件只连一次）
+ *   - run.done/cancelled/error → 忘掉这一轮的状态（板书留着，它是过程记录）
+ * 挂在 project bus 上（broker.getProjectBus 建 bus 时调一次），与 live-turn 折叠器同级。
+ * 失败一律吞掉只 warn：镜像挂了不能影响 run。
+ */
+import path from 'node:path';
+import { readBoard, patchBoard } from '../../projects/board-store.js';
+import { getSharedDir } from '../../projects/workspace.js';
+import { estimateSizeOn } from '../../lib/board-kind-sizes.js';
+import { layerOf, normalizeCanvasId } from '../../lib/canvas-id.js';
+import { textBox, findSpot } from '../../lib/sketch-layout.js';
+import { getViewpoint } from '../../projects/viewpoint-store.js';
+import { renderChalk, writeChalkFile, CHALK_DIR } from '../../lib/chalk.js';
+
+const byRun = new Map();   // runId → { projectId, rel, fileName, items, linked:Set, session }
+const MAX_LINKS_PER_RUN = 24;
+
+function renderList(items) {
+  const lines = ['### 这一轮的步骤', ''];
+  items.forEach((it, i) => {
+    const text = String(it.content || it.activeForm || '').trim() || `步骤 ${i + 1}`;
+    if (it.status === 'completed') lines.push(`- [x] ${text}`);
+    else if (it.status === 'in_progress') lines.push(`- [ ] **→ ${it.activeForm || text}**`);
+    else lines.push(`- [ ] ${text}`);
+  });
+  return lines.join('\n');
+}
+
+/** 工作区相对路径 → 画布 id（产物卡的地址）：精确 > deck: > 站点/word 根 > 原样 */
+export function canvasIdForRel(board, rel) {
+  const r = String(rel || '').replace(/\\/g, '/').replace(/^\.\//, '');
+  if (!r) return null;
+  const objs = board.objects || {};
+  if (objs[r]) return r;
+  const norm = normalizeCanvasId(r);
+  if (norm && objs[norm]) return norm;
+  for (const id of Object.keys(objs)) {
+    const m = /^(site|docx):(.+)$/.exec(id);
+    if (!m) continue;
+    const root = m[2];
+    if (r === root || r.startsWith(`${root}/`)) return id;
+  }
+  // 还没上墙：按形态猜（seated 之后线自然画出来）
+  return norm || r;
+}
+
+async function upsert(st, items) {
+  st.items = items;
+  const body = renderList(items);
+  const content = renderChalk({ body, by: 'agent', tag: st.tag, sessionId: st.session || null });
+  const sharedRoot = getSharedDir(st.projectId);
+  if (!st.fileName) st.fileName = `${new Date().toISOString().replace(/[-:]/g, '').replace(/\.\d+Z$/, '').replace('T', '-')}-步骤.md`;
+  st.rel = await writeChalkFile(sharedRoot, st.fileName, content, { overwrite: !!st.rel });
+  st.fileName = st.rel.split('/').pop();   // 首写可能被加了防撞序号，之后原地覆盖同一个文件
+  const board = await readBoard(st.projectId);
+  const box = textBox(body, 'md', { md: true, wUnits: 14 });
+  const prev = board.objects?.[st.rel];
+  if (prev && Number.isFinite(prev.x)) {
+    // 已有座位：只改高（行数变了）不碰宽 —— 宽由前端量过真值，回写会跟它来回抖（fable P2）
+    await patchBoard(st.projectId, { objects: { [st.rel]: { ...prev, h: box.h } } });
+    return;
+  }
+  // 首次落位：用户视口的空地 > 内容底下（跟 write_on_board 同口径）
+  const known = new Set(Object.keys(board.zones || {}));
+  const obstacles = Object.entries(board.objects || {})
+    .filter(([id, e]) => Number.isFinite(e?.x) && layerOf(id, e, known) === '')
+    .map(([id, e]) => ({ x: e.x, y: e.y, ...estimateSizeOn(board, id, e) }));
+  let bottom = 0; for (const o of obstacles) bottom = Math.max(bottom, o.y + o.h);
+  for (const zz of Object.values(board.zones || {})) if (Number.isFinite(zz?.y)) bottom = Math.max(bottom, zz.y + 240);
+  const vp = getViewpoint(st.projectId);
+  const vpRect = (vp && !vp.layer && vp.camera) ? vp.camera : null;
+  const spot = findSpot({ w: box.w + 24, h: box.h + 24, obstacles, contentBottom: bottom, viewport: vpRect });
+  await patchBoard(st.projectId, { objects: { [st.rel]: { x: spot.x + 12, y: spot.y + 12, z: 1, w: box.w, h: box.h, by: 'agent', tag: st.tag } } });
+}
+
+export function attachBoardTasklist(bus, projectId) {
+  const handle = async (evt) => {
+    if (!evt?.runId) return;
+    if (evt.type === 'run.todo.updated') {
+      const items = Array.isArray(evt.todos) ? evt.todos.filter(t => t && typeof t === 'object') : [];
+      if (!items.length) return;
+      let st = byRun.get(evt.runId);
+      if (!st) {
+        st = { projectId, rel: null, fileName: null, items: [], linked: new Set(), session: evt.sessionId || null, tag: `步骤-${String(evt.runId).slice(-6)}` };
+        byRun.set(evt.runId, st);
+      }
+      await upsert(st, items);
+      bus.publish({ type: 'board.updated', sessionId: null, runId: evt.runId, summary: '步骤清单上板' });
+      return;
+    }
+    if (evt.type === 'run.file_changed') {
+      const st = byRun.get(evt.runId);
+      if (!st?.rel || !evt.filePath) return;
+      const idx = st.items.findIndex(t => t.status === 'in_progress');
+      if (idx < 0) return;
+      // 只连工作区内、非隐藏目录的真产物；每轮封顶（否则 /tmp、.nd、.claude 里的写入会灌一堆
+      // 指向虚空的 auto 线，MAX_BINDINGS 一到用户自己的线都不收 —— fable 08-23 P2）
+      const rel = String(evt.filePath).replace(/\\/g, '/');
+      if (rel.startsWith('/') || rel.split('/').some(seg => seg === '..' || seg.startsWith('.') || seg === 'node_modules')) return;
+      if (rel.startsWith(`${CHALK_DIR}/`) || rel.startsWith('notes/')) return;
+      if (st.linked.size >= MAX_LINKS_PER_RUN) return;
+      const board = await readBoard(st.projectId);
+      const target = canvasIdForRel(board, evt.filePath);
+      if (!target || target === st.rel || target.startsWith(`${CHALK_DIR}/`)) return;
+      if (st.linked.has(target)) return;
+      st.linked.add(target);
+      const id = `b:auto:step:${String(evt.runId).slice(-6)}:${st.linked.size}`;
+      await patchBoard(st.projectId, { bindings: { [id]: { type: 'annotates', from: st.rel, to: target, by: 'auto', label: `第 ${idx + 1} 步`, tag: st.tag } } });
+      bus.publish({ type: 'board.updated', sessionId: null, runId: evt.runId, summary: `第 ${idx + 1} 步 → ${path.basename(target)}` });
+      return;
+    }
+    if (evt.type === 'run.done' || evt.type === 'run.cancelled' || evt.type === 'run.error') {
+      byRun.delete(evt.runId);
+    }
+  };
+  bus.subscribe('*', (evt) => {
+    handle(evt).catch(err => console.warn('[board-tasklist]', err?.message || err));
+  });
+}
+
+export function _resetBoardTasklist() { byRun.clear(); }

package/server/engine/runs/live-turn.js

@@ -1,252 +1,252 @@
-/**
- * server/engine/runs/live-turn.js — 进行中 turn 的物化快照（内存态）
- *
- * 解决的问题：EventBus 是 fire-and-forget + ring buffer（2000 条），token 级
- * streaming 一个 turn 就上万条事件 —— 刷新 / 断线重连后"进行中的 turn"在任何
- * 可恢复的地方都不存在（jsonl 只在 turn 边界 flush）。老架构靠 ?since= 游标 +
- * ring 回放，重连几秒就 gap，gap 补 hydrate 又把已渲染内容反向覆盖。
- *
- * 新范式（快照 + 尾随，2026-07-27 重构）：
- *   - 本模块订阅每个 project bus，把进行中 turn 的事件**同步折叠**成前端
- *     display-message 形态的物化状态（跟 ProjectWorkspace handleEvent 的累加
- *     逻辑同构）
- *   - WS 连接时：jsonl hydrate（已完成 turn）→ ws.live_turn 快照（进行中 turn）
- *     → 从快照 seq 起订阅实时流。ring buffer 大小从此只影响极小的同步窗口，
- *     不再影响正确性
- *   - turn 结束（done / error / cancelled）或 session 结束即清，内存占用 =
- *     活跃 turn 数 × 单 turn 消息体量（tool output 截断到 16k）
- *
- * 折叠规则跟前端 handleEvent 对齐（改前端渲染逻辑时两边同步改）：
- *   run.delta.text / thinking       → 同 role 连续累加一条消息
- *   run.tool_use.started            → push tool 消息 status='running'
- *   run.delta.tool_use              → 补 toolInput
- *   run.delta.tool_result           → 补 status / output / error（images 不进快照，太大）
- *   run.todo.updated                → todos 覆盖
- *   run.context_usage               → contextUsage 覆盖
- *   run.done / error / cancelled    → 标记 ended（保留 GRACE 毫秒，见下），不再折叠
- *   run.query.end                   → 清
- *
- * turn 结束后为什么还留一小会（2026-07-28）：jsonl 是 SDK 子进程按 block 逐条写的，
- * 我们读 jsonl 与 turn 收尾之间有几百毫秒的错位窗口。这段时间内重连，若快照已经
- * 没了，尾随订阅会把已经落进 jsonl 的那几条 delta 再放一遍 → 正文重复。留 GRACE
- * 毫秒让"本轮由快照权威、hydrate 裁掉本轮"这条规则在收尾瞬间同样成立。
- */
-
-const MAX_TOOL_TEXT = 16_000;
-// 3s：够盖住"读 jsonl 的几百毫秒"这个错位窗口，又短到收尾后的重连基本不会
-// 落在里面（快照不带 tool_result 的图片，长时间用快照顶替 hydrate 会丢缩略图）。
-const ENDED_GRACE_MS = 3_000;
-
-/** @type {Map<string, object>} sessionId → live turn state */
-const liveTurns = new Map();
-
-/**
- * sessionId → 最近一次 run.context_usage 事件（2026-07-30）
- *
- * 跟 liveTurns 分开活着：turn 一结束 liveTurns 就清，但"这个会话现在装了多少上下文"
- * 在两轮之间照样成立 —— 而那恰恰是用户最想看它的时刻（要不要先压缩再开新活）。
- *
- * query 结束也**不清**：关掉标签页就会触发 grace 超时关 session，而下次打开这个会话
- * 时 SDK 从同一份 jsonl resume，上下文体量基本还是那么大。这时给个带"当前没有活跃
- * 会话"标注的旧数字（live:false），比一句"还没开始对话"有用得多。只有 query 活着时才向 SDK 现问
- * （见 GET /sessions/:sid/context-usage），所以准确的那条路一直优先。
- *
- * 只活在内存里：进程重启就没了，下一轮 turn 自然补上。
- */
-const lastUsage = new Map();
-const LAST_USAGE_CAP = 200;
-
-export function getLastContextUsage(sessionId) {
-  return lastUsage.get(sessionId) || null;
-}
-
-/**
- * 不变量守卫：只记 Events.contextUsage 构造出来的那种形状。
- *
- * `run.context_usage` 曾经有两个生产者，字段名对不上：session-loop 每条 assistant
- * message 后发 { totalTokens, maxTokens, percentage }（前端读这套），hooks.js 的 Stop
- * handler 每轮收尾发 { used, max, percent, categories }。前端靠 store 的"不覆盖已有值"
- * 侥幸没显形，但每轮的**最后**一条恰好总是后者，凡是"取最新一条"的下游拿到的都是
- * 一片 undefined —— 这个记忆层就是这么栽的。两个生产者已经合并成一个构造函数
- * （2026-07-30），这里留一道守卫：以后再冒出第三种形状，是它被丢掉，不是这里出错数。
- */
-function rememberUsage(sid, evt) {
-  if (typeof evt.totalTokens !== 'number') return;
-  if (lastUsage.size >= LAST_USAGE_CAP && !lastUsage.has(sid)) {
-    // 先进先出丢一条：进程活得久了不至于攒着所有历史 session
-    const oldest = lastUsage.keys().next().value;
-    if (oldest) lastUsage.delete(oldest);
-  }
-  lastUsage.set(sid, evt);
-}
-
-function truncate(s) {
-  if (typeof s !== 'string') return s;
-  if (s.length <= MAX_TOOL_TEXT) return s;
-  return s.slice(0, MAX_TOOL_TEXT) + `\n…[截断，共 ${s.length} 字符]`;
-}
-
-/**
- * 给 project bus 挂折叠订阅（幂等 —— broker.getProjectBus 每次创建 bus 时调）。
- */
-export function attachLiveTurnTracker(bus) {
-  if (bus.__liveTurnTracked) return;
-  bus.__liveTurnTracked = true;
-  bus.subscribe('*', fold);
-}
-
-/**
- * 取 session 当前 turn 的快照；没有在跑、且上一轮已过 grace 期 → null。
- * 返回值直接可作 ws.live_turn 帧 payload（messages 是前端 display 形态）。
- *
- * running=false 表示这是刚结束那一轮的尾巴（grace 期内），前端据此**只合并消息、
- * 不把自己切回 streaming 态**。
- */
-export function getLiveTurnSnapshot(sessionId) {
-  const st = liveTurns.get(sessionId);
-  if (!st) return null;
-  if (st.endedAt && Date.now() - st.endedAt > ENDED_GRACE_MS) {
-    liveTurns.delete(sessionId);
-    return null;
-  }
-  return {
-    runId: st.runId,
-    seq: st.seq,
-    startedAt: st.startedAt,
-    running: !st.endedAt,
-    messages: st.messages,
-    todos: st.todos,
-    contextUsage: st.contextUsage,
-  };
-}
-
-function fold(evt) {
-  const sid = evt.sessionId;
-  if (!sid) return;
-
-  // 记在 liveTurns 之外：turn 结束、快照删掉之后，这个数字还要继续给 composer
-  // 的 [+] 菜单用。放在 st 判空之前，快照已经清了也照记。
-  if (evt.type === 'run.context_usage') rememberUsage(sid, evt);
-
-  if (evt.type === 'run.start') {
-    liveTurns.set(sid, {
-      runId: evt.runId || null,
-      startedAt: evt.ts || new Date().toISOString(),
-      seq: evt.seq || 0,
-      messages: [],
-      todos: [],
-      contextUsage: null,
-      endedAt: null,
-      _msgCounter: 0,
-    });
-    return;
-  }
-
-  const st = liveTurns.get(sid);
-  if (!st) return;
-
-  // 已收尾的那一轮只留着给 grace 期内的重连当权威快照，不再吸新事件
-  // （新一轮由上面的 run.start 整块换掉）。seq 照常推进，免得尾随订阅从旧游标
-  // 起把这轮已经放过的事件再放一遍。
-  if (st.endedAt) {
-    if (evt.type === 'run.query.end' || Date.now() - st.endedAt > ENDED_GRACE_MS) {
-      liveTurns.delete(sid);
-      return;
-    }
-    if (typeof evt.seq === 'number' && evt.seq > st.seq) st.seq = evt.seq;
-    return;
-  }
-
-  // stale 事件（老 turn 的尾巴）不折叠也不清新 turn 的状态
-  const runMatches = !evt.runId || !st.runId || evt.runId === st.runId;
-
-  switch (evt.type) {
-    case 'run.delta.text':
-      if (runMatches) appendText(st, 'assistant', evt.text, evt.parentToolUseId);
-      break;
-    case 'run.delta.thinking':
-      if (runMatches) appendText(st, 'thinking', evt.text, evt.parentToolUseId);
-      break;
-    case 'run.tool_use.started':
-      if (runMatches && evt.blockId && !st.messages.some(m => m.id === evt.blockId)) {
-        st.messages.push({
-          id: evt.blockId, role: 'tool', toolName: evt.name,
-          toolInput: undefined, status: 'running', runId: st.runId,
-          ...(evt.parentToolUseId ? { parentToolUseId: evt.parentToolUseId } : {}),
-        });
-      }
-      break;
-    case 'run.delta.tool_use': {
-      if (!runMatches) break;
-      const existing = st.messages.find(m => m.role === 'tool' && m.id === evt.blockId);
-      if (existing) existing.toolInput = evt.input;
-      else if (evt.blockId) {
-        st.messages.push({
-          id: evt.blockId, role: 'tool', toolName: evt.name,
-          toolInput: evt.input, status: 'running', runId: st.runId,
-          ...(evt.parentToolUseId ? { parentToolUseId: evt.parentToolUseId } : {}),
-        });
-      }
-      break;
-    }
-    case 'run.delta.tool_result': {
-      if (!runMatches) break;
-      const tool = st.messages.find(m => m.role === 'tool' && m.id === evt.blockId);
-      if (tool) {
-        tool.status = evt.ok ? 'success' : 'error';
-        if (evt.output !== undefined) tool.toolOutput = truncate(typeof evt.output === 'string' ? evt.output : JSON.stringify(evt.output));
-        if (evt.error) tool.toolError = truncate(typeof evt.error === 'string' ? evt.error : JSON.stringify(evt.error));
-        // images 不进快照：base64 体积大，turn 结束后 jsonl hydrate 会带回来
-      }
-      break;
-    }
-    case 'run.tool_use_summary': {
-      if (!runMatches || !evt.summary) break;
-      const ids = Array.isArray(evt.blockIds) ? evt.blockIds : [];
-      const hit = st.messages.find(m => m.role === 'tool' && ids.includes(m.id));
-      if (hit) hit.groupSummary = evt.summary;
-      break;
-    }
-    case 'run.todo.updated':
-      if (runMatches && Array.isArray(evt.todos)) st.todos = evt.todos;
-      break;
-    case 'run.context_usage':
-      if (runMatches) st.contextUsage = evt;
-      break;
-    case 'run.done':
-    case 'run.error':
-    case 'run.cancelled':
-      // 不立刻删：留 grace 期给"收尾瞬间重连"当权威快照（见文件头说明）
-      if (runMatches) {
-        st.endedAt = Date.now();
-        if (typeof evt.seq === 'number' && evt.seq > st.seq) st.seq = evt.seq;
-      }
-      return;
-    case 'run.query.end':
-      liveTurns.delete(sid);
-      return;
-    default:
-      break;
-  }
-
-  // 所有本 session 事件都推进快照游标（包括未折叠类型）——
-  // 重连订阅从 seq 起，不折叠的事件类型（queue depth 等）丢了也无碍（幂等 UI 状态）
-  if (typeof evt.seq === 'number' && evt.seq > st.seq) st.seq = evt.seq;
-}
-
-function appendText(st, role, text, parentToolUseId = null) {
-  if (!text) return;
-  const last = st.messages[st.messages.length - 1];
-  // 子代理时间轴：不同 parent 的流不互吸（跟前端 lib/chat-stream.js 同构）
-  if (last && last.role === role && (last.parentToolUseId || null) === (parentToolUseId || null)) {
-    last.content = (last.content || '') + text;
-    return;
-  }
-  st.messages.push({
-    id: `${st.runId || 'live'}:m${st._msgCounter++}`,
-    ...(parentToolUseId ? { parentToolUseId } : {}),
-    role,
-    content: text,
-    runId: st.runId,
-  });
-}
+/**
+ * server/engine/runs/live-turn.js — 进行中 turn 的物化快照（内存态）
+ *
+ * 解决的问题：EventBus 是 fire-and-forget + ring buffer（2000 条），token 级
+ * streaming 一个 turn 就上万条事件 —— 刷新 / 断线重连后"进行中的 turn"在任何
+ * 可恢复的地方都不存在（jsonl 只在 turn 边界 flush）。老架构靠 ?since= 游标 +
+ * ring 回放，重连几秒就 gap，gap 补 hydrate 又把已渲染内容反向覆盖。
+ *
+ * 新范式（快照 + 尾随，2026-07-27 重构）：
+ *   - 本模块订阅每个 project bus，把进行中 turn 的事件**同步折叠**成前端
+ *     display-message 形态的物化状态（跟 ProjectWorkspace handleEvent 的累加
+ *     逻辑同构）
+ *   - WS 连接时：jsonl hydrate（已完成 turn）→ ws.live_turn 快照（进行中 turn）
+ *     → 从快照 seq 起订阅实时流。ring buffer 大小从此只影响极小的同步窗口，
+ *     不再影响正确性
+ *   - turn 结束（done / error / cancelled）或 session 结束即清，内存占用 =
+ *     活跃 turn 数 × 单 turn 消息体量（tool output 截断到 16k）
+ *
+ * 折叠规则跟前端 handleEvent 对齐（改前端渲染逻辑时两边同步改）：
+ *   run.delta.text / thinking       → 同 role 连续累加一条消息
+ *   run.tool_use.started            → push tool 消息 status='running'
+ *   run.delta.tool_use              → 补 toolInput
+ *   run.delta.tool_result           → 补 status / output / error（images 不进快照，太大）
+ *   run.todo.updated                → todos 覆盖
+ *   run.context_usage               → contextUsage 覆盖
+ *   run.done / error / cancelled    → 标记 ended（保留 GRACE 毫秒，见下），不再折叠
+ *   run.query.end                   → 清
+ *
+ * turn 结束后为什么还留一小会（2026-07-28）：jsonl 是 SDK 子进程按 block 逐条写的，
+ * 我们读 jsonl 与 turn 收尾之间有几百毫秒的错位窗口。这段时间内重连，若快照已经
+ * 没了，尾随订阅会把已经落进 jsonl 的那几条 delta 再放一遍 → 正文重复。留 GRACE
+ * 毫秒让"本轮由快照权威、hydrate 裁掉本轮"这条规则在收尾瞬间同样成立。
+ */
+
+const MAX_TOOL_TEXT = 16_000;
+// 3s：够盖住"读 jsonl 的几百毫秒"这个错位窗口，又短到收尾后的重连基本不会
+// 落在里面（快照不带 tool_result 的图片，长时间用快照顶替 hydrate 会丢缩略图）。
+const ENDED_GRACE_MS = 3_000;
+
+/** @type {Map<string, object>} sessionId → live turn state */
+const liveTurns = new Map();
+
+/**
+ * sessionId → 最近一次 run.context_usage 事件（2026-07-30）
+ *
+ * 跟 liveTurns 分开活着：turn 一结束 liveTurns 就清，但"这个会话现在装了多少上下文"
+ * 在两轮之间照样成立 —— 而那恰恰是用户最想看它的时刻（要不要先压缩再开新活）。
+ *
+ * query 结束也**不清**：关掉标签页就会触发 grace 超时关 session，而下次打开这个会话
+ * 时 SDK 从同一份 jsonl resume，上下文体量基本还是那么大。这时给个带"当前没有活跃
+ * 会话"标注的旧数字（live:false），比一句"还没开始对话"有用得多。只有 query 活着时才向 SDK 现问
+ * （见 GET /sessions/:sid/context-usage），所以准确的那条路一直优先。
+ *
+ * 只活在内存里：进程重启就没了，下一轮 turn 自然补上。
+ */
+const lastUsage = new Map();
+const LAST_USAGE_CAP = 200;
+
+export function getLastContextUsage(sessionId) {
+  return lastUsage.get(sessionId) || null;
+}
+
+/**
+ * 不变量守卫：只记 Events.contextUsage 构造出来的那种形状。
+ *
+ * `run.context_usage` 曾经有两个生产者，字段名对不上：session-loop 每条 assistant
+ * message 后发 { totalTokens, maxTokens, percentage }（前端读这套），hooks.js 的 Stop
+ * handler 每轮收尾发 { used, max, percent, categories }。前端靠 store 的"不覆盖已有值"
+ * 侥幸没显形，但每轮的**最后**一条恰好总是后者，凡是"取最新一条"的下游拿到的都是
+ * 一片 undefined —— 这个记忆层就是这么栽的。两个生产者已经合并成一个构造函数
+ * （2026-07-30），这里留一道守卫：以后再冒出第三种形状，是它被丢掉，不是这里出错数。
+ */
+function rememberUsage(sid, evt) {
+  if (typeof evt.totalTokens !== 'number') return;
+  if (lastUsage.size >= LAST_USAGE_CAP && !lastUsage.has(sid)) {
+    // 先进先出丢一条：进程活得久了不至于攒着所有历史 session
+    const oldest = lastUsage.keys().next().value;
+    if (oldest) lastUsage.delete(oldest);
+  }
+  lastUsage.set(sid, evt);
+}
+
+function truncate(s) {
+  if (typeof s !== 'string') return s;
+  if (s.length <= MAX_TOOL_TEXT) return s;
+  return s.slice(0, MAX_TOOL_TEXT) + `\n…[截断，共 ${s.length} 字符]`;
+}
+
+/**
+ * 给 project bus 挂折叠订阅（幂等 —— broker.getProjectBus 每次创建 bus 时调）。
+ */
+export function attachLiveTurnTracker(bus) {
+  if (bus.__liveTurnTracked) return;
+  bus.__liveTurnTracked = true;
+  bus.subscribe('*', fold);
+}
+
+/**
+ * 取 session 当前 turn 的快照；没有在跑、且上一轮已过 grace 期 → null。
+ * 返回值直接可作 ws.live_turn 帧 payload（messages 是前端 display 形态）。
+ *
+ * running=false 表示这是刚结束那一轮的尾巴（grace 期内），前端据此**只合并消息、
+ * 不把自己切回 streaming 态**。
+ */
+export function getLiveTurnSnapshot(sessionId) {
+  const st = liveTurns.get(sessionId);
+  if (!st) return null;
+  if (st.endedAt && Date.now() - st.endedAt > ENDED_GRACE_MS) {
+    liveTurns.delete(sessionId);
+    return null;
+  }
+  return {
+    runId: st.runId,
+    seq: st.seq,
+    startedAt: st.startedAt,
+    running: !st.endedAt,
+    messages: st.messages,
+    todos: st.todos,
+    contextUsage: st.contextUsage,
+  };
+}
+
+function fold(evt) {
+  const sid = evt.sessionId;
+  if (!sid) return;
+
+  // 记在 liveTurns 之外：turn 结束、快照删掉之后，这个数字还要继续给 composer
+  // 的 [+] 菜单用。放在 st 判空之前，快照已经清了也照记。
+  if (evt.type === 'run.context_usage') rememberUsage(sid, evt);
+
+  if (evt.type === 'run.start') {
+    liveTurns.set(sid, {
+      runId: evt.runId || null,
+      startedAt: evt.ts || new Date().toISOString(),
+      seq: evt.seq || 0,
+      messages: [],
+      todos: [],
+      contextUsage: null,
+      endedAt: null,
+      _msgCounter: 0,
+    });
+    return;
+  }
+
+  const st = liveTurns.get(sid);
+  if (!st) return;
+
+  // 已收尾的那一轮只留着给 grace 期内的重连当权威快照，不再吸新事件
+  // （新一轮由上面的 run.start 整块换掉）。seq 照常推进，免得尾随订阅从旧游标
+  // 起把这轮已经放过的事件再放一遍。
+  if (st.endedAt) {
+    if (evt.type === 'run.query.end' || Date.now() - st.endedAt > ENDED_GRACE_MS) {
+      liveTurns.delete(sid);
+      return;
+    }
+    if (typeof evt.seq === 'number' && evt.seq > st.seq) st.seq = evt.seq;
+    return;
+  }
+
+  // stale 事件（老 turn 的尾巴）不折叠也不清新 turn 的状态
+  const runMatches = !evt.runId || !st.runId || evt.runId === st.runId;
+
+  switch (evt.type) {
+    case 'run.delta.text':
+      if (runMatches) appendText(st, 'assistant', evt.text, evt.parentToolUseId);
+      break;
+    case 'run.delta.thinking':
+      if (runMatches) appendText(st, 'thinking', evt.text, evt.parentToolUseId);
+      break;
+    case 'run.tool_use.started':
+      if (runMatches && evt.blockId && !st.messages.some(m => m.id === evt.blockId)) {
+        st.messages.push({
+          id: evt.blockId, role: 'tool', toolName: evt.name,
+          toolInput: undefined, status: 'running', runId: st.runId,
+          ...(evt.parentToolUseId ? { parentToolUseId: evt.parentToolUseId } : {}),
+        });
+      }
+      break;
+    case 'run.delta.tool_use': {
+      if (!runMatches) break;
+      const existing = st.messages.find(m => m.role === 'tool' && m.id === evt.blockId);
+      if (existing) existing.toolInput = evt.input;
+      else if (evt.blockId) {
+        st.messages.push({
+          id: evt.blockId, role: 'tool', toolName: evt.name,
+          toolInput: evt.input, status: 'running', runId: st.runId,
+          ...(evt.parentToolUseId ? { parentToolUseId: evt.parentToolUseId } : {}),
+        });
+      }
+      break;
+    }
+    case 'run.delta.tool_result': {
+      if (!runMatches) break;
+      const tool = st.messages.find(m => m.role === 'tool' && m.id === evt.blockId);
+      if (tool) {
+        tool.status = evt.ok ? 'success' : 'error';
+        if (evt.output !== undefined) tool.toolOutput = truncate(typeof evt.output === 'string' ? evt.output : JSON.stringify(evt.output));
+        if (evt.error) tool.toolError = truncate(typeof evt.error === 'string' ? evt.error : JSON.stringify(evt.error));
+        // images 不进快照：base64 体积大，turn 结束后 jsonl hydrate 会带回来
+      }
+      break;
+    }
+    case 'run.tool_use_summary': {
+      if (!runMatches || !evt.summary) break;
+      const ids = Array.isArray(evt.blockIds) ? evt.blockIds : [];
+      const hit = st.messages.find(m => m.role === 'tool' && ids.includes(m.id));
+      if (hit) hit.groupSummary = evt.summary;
+      break;
+    }
+    case 'run.todo.updated':
+      if (runMatches && Array.isArray(evt.todos)) st.todos = evt.todos;
+      break;
+    case 'run.context_usage':
+      if (runMatches) st.contextUsage = evt;
+      break;
+    case 'run.done':
+    case 'run.error':
+    case 'run.cancelled':
+      // 不立刻删：留 grace 期给"收尾瞬间重连"当权威快照（见文件头说明）
+      if (runMatches) {
+        st.endedAt = Date.now();
+        if (typeof evt.seq === 'number' && evt.seq > st.seq) st.seq = evt.seq;
+      }
+      return;
+    case 'run.query.end':
+      liveTurns.delete(sid);
+      return;
+    default:
+      break;
+  }
+
+  // 所有本 session 事件都推进快照游标（包括未折叠类型）——
+  // 重连订阅从 seq 起，不折叠的事件类型（queue depth 等）丢了也无碍（幂等 UI 状态）
+  if (typeof evt.seq === 'number' && evt.seq > st.seq) st.seq = evt.seq;
+}
+
+function appendText(st, role, text, parentToolUseId = null) {
+  if (!text) return;
+  const last = st.messages[st.messages.length - 1];
+  // 子代理时间轴：不同 parent 的流不互吸（跟前端 lib/chat-stream.js 同构）
+  if (last && last.role === role && (last.parentToolUseId || null) === (parentToolUseId || null)) {
+    last.content = (last.content || '') + text;
+    return;
+  }
+  st.messages.push({
+    id: `${st.runId || 'live'}:m${st._msgCounter++}`,
+    ...(parentToolUseId ? { parentToolUseId } : {}),
+    role,
+    content: text,
+    runId: st.runId,
+  });
+}