@xiaobuyu/nodesign 0.0.6 → 0.0.8

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

@@ -0,0 +1,272 @@
+/**
+ * server/engine/runs/board-seater.js —— 服务端入座（2026-08-25 范式重做④）
+ *
+ * 病根（08-25 信箱实证）：入座算法原来只住前端 board-seating.js，只在浏览器渲染
+ * 那一层时发生。agent 写完 `小说/第一章.md`，26 秒后 `write_on_board {near:它}`
+ * 失败「还没有座位」，6 小时后依然没有 —— 用户没打开过那个文件夹。而工具描述
+ * 正教 agent「Use it right after you finish something」。read_board 同病：刚写的
+ * 文件看不见 → agent 误判"没上画布" → 去 pin → 重影。
+ *
+ * 这里把入座下沉：挂在 project bus 上收本轮的 run.file_changed，**回合末一批**
+ * 排座（站主拍板的时机）。判据不新写黑名单 —— 复用 task-scan 的同一套排除件
+ * （隐藏目录 / node_modules / _drafts / 保留文件），层隔离照 layerOf。
+ *
+ * 板书领养：prelude 说「你写的每张 .md 在桌面上渲成贴纸」，但 Write 直接落
+ * notes/板书/ 的文件从来不上墙（10-05 friction）。这里把它领养成正式板书：
+ * 认 frontmatter（nd: chalk 的 anchor/reply_to/tag），照 write_on_board 同款
+ * 画线落座 —— 从此那句 prelude 是真话。
+ *
+ * 座位一律 seat:'auto'（可被前端重排）；已有座位的绝不动。
+ *
+ * ## 2026-08-30 刀 G：入座**不再自己铺纸**
+ *
+ * 站主拍板：「产物也需要 agent 提前规划放置位置落在纸上，甚至包括文件夹」。
+ * 在此之前这里排不下就 allocateSheetRect 翻一张新纸 —— 那张纸没标题、没版位、
+ * 署名 by:'agent'，而 agent 根本不知道它存在。真板实证（proj_mtfix5rv）：agent
+ * Write 了 CLAUDE.md，入座顺手铺了 p1，agent 随后自己 open_sheet 开了 p2，板上
+ * 从此永久留着一张空白无规划的纸。这正是「机器是兜底不是版面」要禁的事。
+ *
+ * 现在的三档：
+ *   ① 这一页规划了 `for:'artifacts'` 的地 → 落进那块地（agent 事前说了放哪儿）
+ *   ② 没规划但当前纸还排得下 → 纸内顺排（兜底，跟以前一样）
+ *   ③ 排不下 → **不铺纸**，进 board.pending 待摆队列，每回合状态块点名，
+ *      等 agent 规划出地方（open_sheet{plan} / pin_to_board 点名）再落座。
+ * 唯一的例外是**一张纸都还没有**：那不是翻页，是开工，照旧铺第一张。
+ *
+ * ## 2026-08-30 暂存架：机器的手只够得到架
+ *
+ * 上面那个「开工例外」当天就翻了车（proj_mtfz7n8p）：web_search 采回的参考图
+ * 先于 agent 的第一笔到场，入座器铺了 p1 —— 第一张纸又成了机器铺的，agent
+ * 不知道它存在，自己的板书全在缝里流。站主拍板：**机器从此完全不产纸、
+ * 也不往纸面顺排**。三档收成两档：
+ *   ① 这一页规划了 `for:'artifacts'` 的地 → 落进那块地（agent 事前说了放哪儿）
+ *   ② 其余（没规划 / 排不下 / 一张纸都没有）→ 一律上暂存架（lib/board-shelf.js，
+ *      seat:'shelf'），每回合状态块点名，agent 用 pin_to_board / edit_board move
+ *      安置。旧 board.pending 队列并进架上（它们从「看不见」变「看得见」）。
+ */
+
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { readBoard, patchBoard } from '../../projects/board-store.js';
+import { getSharedDir } from '../../projects/workspace.js';
+import { estimateSizeOn } from '../../lib/board-kind-sizes.js';
+import { obstaclesIn } from '../../lib/board-obstacles.js';
+import { layerOf, normalizeCanvasId } from '../../lib/canvas-id.js';
+import {
+  currentSheet, placeThread, placeBeside, slotRectOf, nextSpotInSlot,
+} from '../../lib/board-sheets.js';
+import { resolveShelfOrigin, nextShelfSpot, FOLDER_BOX } from '../../lib/board-shelf.js';
+import { textBox } from '../../lib/sketch-layout.js';
+import { getViewpoint } from '../../projects/viewpoint-store.js';
+import { parseChalk, CHALK_DIR } from '../../lib/chalk.js';
+import { isReservedFile, HARD_IGNORE_DIRS, RESERVED_DIRS, DRAFTS_DIR } from '../../lib/task-scan.js';
+import { applyFollows } from '../../lib/board-follow.js';
+import { canvasIdForRel } from './board-tasklist.js';
+
+const MAX_SEATS_PER_RUN = 24;   // 一轮生成几百个文件的（构建产物漏网）也别刷爆板
+
+/** 会渲染成卡的才配座位：跟 /artifacts 扫描同一套排除精神 */
+export function seatable(rel) {
+  if (typeof rel !== 'string' || !rel || rel.length > 300) return false;
+  if (rel.startsWith('/') || rel.includes('\\') || rel.includes('\0')) return false;
+  const segs = rel.split('/');
+  if (segs.some(s => s === '..' || s === DRAFTS_DIR || HARD_IGNORE_DIRS.has(s))) return false;
+  // 点开头的段（.nd/.claude/.thumbnails…）整条不渲染
+  if (segs.some(s => s.startsWith('.'))) return false;
+  if (isReservedFile(segs[segs.length - 1])) return false;
+  return true;
+}
+
+let seq = 0;
+const stamp = () => `${Date.now().toString(36)}${(seq++ % 1000).toString(36)}`;
+
+/**
+ * 给一批相对路径排座（幂等：已有座位的跳过）。导出给测试与手动对账用。
+ * @returns {Promise<{seated: number, lines: number}>}
+ */
+export async function seatArtifacts(projectId, rels) {
+  const sharedRoot = getSharedDir(projectId);
+  const board = await readBoard(projectId);
+  // 待摆队列先并进来（刀 G）：上一批排不下的，这一批 agent 可能已经规划出地方了。
+  // 排在新来的前面 —— 等得久的先落。
+  const queued = Array.isArray(board.pending) ? board.pending : [];
+  const uniq = [...new Set([...queued, ...rels])].filter(seatable).slice(0, MAX_SEATS_PER_RUN * 2);
+  if (!uniq.length) return { seated: 0, lines: 0, pending: 0 };
+  const known = new Set(Object.keys(board.zones || {}));
+  const vp = getViewpoint(projectId);
+  const objects = {}; const bindings = {};
+  // 本批内后来者要避开先来者：live 副本随排随更新
+  const live = { ...board.objects };
+  // 暂存架（2026-08-30）：批内原点算一次（架立了就不挪）；本批内后来者靠
+  // live 障碍矩形自然码在先来者下面。
+  const rootCam = (vp?.camera && !vp.layer) ? vp.camera : null;
+  const shelfOrigin = resolveShelfOrigin(board, rootCam);
+  const stillPending = [];          // 本批没轮到的（只剩封顶截流一种情况）
+  let seated = 0; let lines = 0; let shelved = 0;
+
+  // 文件夹卡也上架（2026-08-30，站主拍板「文件夹和单个文件一律落暂存区」）：
+  // 这批文件揭示的顶层目录，还没有文件夹卡坐标的，先码在架上 —— 前端的
+  // newStackedZoneRect 只给没坐标的排位，这里写了它就不再排。判据与 seatable
+  // 同一套精神：保留目录（assets/notes/…）和隐藏目录不是用户的文件夹。
+  const zonesPatch = {};
+  const zoneRects = Object.entries(board.zones || {})
+    .filter(([, z]) => Number.isFinite(z?.x) && Number.isFinite(z?.y))
+    .map(([, z]) => ({ x: z.x, y: z.y, w: FOLDER_BOX.w, h: FOLDER_BOX.h }));
+  for (const rel of uniq) {
+    const segs = rel.split('/');
+    if (segs.length < 2 || !seatable(rel)) continue;
+    const top = segs[0];
+    if (RESERVED_DIRS.has(top) || zonesPatch[top]) continue;
+    if (board.zones?.[top] && Number.isFinite(board.zones[top].x)) continue;
+    const rootRects = Object.entries(live)
+      .filter(([id, e]) => Number.isFinite(e?.x) && layerOf(id, e, known) === '')
+      .map(([id, e]) => ({ x: e.x, y: e.y, ...estimateSizeOn(board, id, e) }));
+    const spot = nextShelfSpot(shelfOrigin, [...rootRects, ...zoneRects]);
+    zonesPatch[top] = { x: spot.x, y: spot.y };
+    zoneRects.push({ x: spot.x, y: spot.y, w: FOLDER_BOX.w, h: FOLDER_BOX.h });
+    known.add(top);   // 这批的文件按新文件夹归层（跟前端 homeOf 同判）
+  }
+
+  for (const rel of uniq) {
+    const id = canvasIdForRel({ objects: live, zones: board.zones }, rel);
+    if (!id) continue;
+    if (live[id] && Number.isFinite(live[id].x)) continue;   // 已有座位
+    // 封顶截流：没轮到的留在队列里下批再来（暂存架永远有地方，这是唯一的排队原因）
+    if (seated >= MAX_SEATS_PER_RUN) { stillPending.push(rel); continue; }
+    // 文件还在才入座（本轮建又删的别复活）
+    try { await fs.access(path.join(sharedRoot, rel)); } catch { continue; }
+
+    let box = estimateSizeOn(board, id, null);
+    let inSlot = null;               // 落进了哪块规划好的产物地
+    let anchorRect = null; let replyRect = null;
+    let anchorId = null; let parentId = null; let tag = null; let by = null;
+
+    // 板书领养：Write 直接落盘的 notes/板书/*.md 按 frontmatter 接线
+    if (rel.startsWith(`${CHALK_DIR}/`) && rel.endsWith('.md')) {
+      try {
+        const raw = await fs.readFile(path.join(sharedRoot, rel), 'utf8');
+        const { body, chalk } = parseChalk(raw);
+        if (chalk) {
+          by = chalk.by;
+          tag = chalk.tag || null;
+          box = textBox(body, 'md', { md: true });
+          if (chalk.anchor) {
+            const aid = normalizeCanvasId(chalk.anchor);
+            const e = aid && live[aid];
+            if (e && Number.isFinite(e.x)) { anchorId = aid; anchorRect = { x: e.x, y: e.y, ...estimateSizeOn(board, aid, e) }; }
+          }
+          if (chalk.replyTo) {
+            const pid2 = normalizeCanvasId(chalk.replyTo);
+            const e = pid2 && live[pid2];
+            if (e && Number.isFinite(e.x)) { parentId = pid2; replyRect = { x: e.x, y: e.y, ...estimateSizeOn(board, pid2, e) }; }
+          }
+        }
+      } catch { /* 读不到就按普通文件排 */ }
+    }
+
+    const zone = layerOf(id, live[id], known);
+    const obstacles = obstaclesIn(board, zone, { objects: live, exclude: [id] });
+    // 落位（2026-08-30 暂存架）：线程接楼 > 锚点贴放 > 产物地（根层）> 暂存架（根层）
+    // / 内容底下（文件夹层）。机器不产纸、不往纸面顺排。
+    const liveBoard = { ...board, objects: live };
+    let placed = null; let onShelf = false;
+    if (replyRect) {
+      const p = placeThread(liveBoard, replyRect, box, { obstacles });
+      placed = p.sheetFull ? null : p;   // 线程纸满：接不了楼就上暂存架（线还在，找得回）
+    }
+    if (!placed && anchorRect) placed = placeBeside(anchorRect, box, 'below');
+    if (!placed && !zone) {
+      const cur = currentSheet(liveBoard, null);
+      // ① agent 事前规划的产物地（slot.for === 'artifacts'）
+      if (cur) {
+        const named = Object.entries(cur.slots || {}).find(([, sl]) => sl.for === 'artifacts');
+        if (named) {
+          const r = slotRectOf(cur, named[0]);
+          const spot = r ? nextSpotInSlot(liveBoard, r, box) : { full: true };
+          if (!spot.full) { placed = spot; inSlot = named[0]; }
+        }
+      }
+      // ② 其余一律上暂存架：agent 没说放哪儿的，机器不替它定版面。
+      //    文件夹卡不在 objects 里，避让要把 zoneRects 一并算上
+      if (!placed) {
+        placed = nextShelfSpot(shelfOrigin, [...obstacles, ...zoneRects]);
+        onShelf = true;
+      }
+    }
+    if (!placed) {
+      // 文件夹层：这一层内容底下接着排（没有纸也没有启发式 —— 单条规则）
+      const left = obstacles.length ? Math.min(...obstacles.map(o => o.x)) : 10;
+      const bottom = obstacles.reduce((m, o) => Math.max(m, o.y + o.h), 0);
+      placed = { x: Math.round(left), y: Math.round(bottom) + 40 };
+    }
+    const entry = {
+      x: Math.round(placed.x), y: Math.round(placed.y), z: 1,
+      w: Math.round(box.w), h: Math.round(box.h),
+      zone, seat: onShelf ? 'shelf' : 'auto',
+      ...(by ? { by } : {}), ...(tag ? { tag } : {}),
+    };
+    if (onShelf) shelved += 1;
+    objects[id] = entry; live[id] = entry;
+    seated += 1;
+    if (anchorId) { bindings[`b:a${stamp()}`] = { type: 'annotates', from: id, to: anchorId, by: by || 'agent', ...(tag ? { tag } : {}) }; lines += 1; }
+    if (parentId) { bindings[`b:a${stamp()}`] = { type: 'flow', from: parentId, to: id, by: by || 'agent', material: 'pencil', ...(tag ? { tag } : {}) }; lines += 1; }
+  }
+
+  // 队列整表写回：**必须无条件写**，哪怕这一批一件都没坐下 ——
+  // 队列清空也是一次状态变化（旧 pending 这一轮上了架，队列该空）。
+  const pendingChanged = JSON.stringify(queued) !== JSON.stringify(stillPending);
+  const zoned = Object.keys(zonesPatch).length;
+  if (seated || pendingChanged || zoned) {
+    await patchBoard(projectId, {
+      ...(seated ? { objects, bindings } : {}),
+      ...(zoned ? { zones: zonesPatch } : {}),
+      ...(pendingChanged ? { pending: stillPending } : {}),
+      // 架的原点：第一次用到（或被纸压住重立）才落盘
+      ...((shelved || zoned) && shelfOrigin.changed ? { shelf: { x: shelfOrigin.x, y: shelfOrigin.y } } : {}),
+    });
+  }
+  // 领养的板书带 tag：有人跟着这个 tag（状态板）就自动重锚（fail-soft）
+  for (const [id, e] of Object.entries(objects)) {
+    if (e?.tag) { try { await applyFollows(projectId, { tag: e.tag, newId: id }); } catch { /* */ } }
+  }
+  return { seated, lines, shelved, pending: stillPending.length };
+}
+
+/**
+ * 挂 project bus（与 board-tasklist 同栖）。时机 = **即时**：file_changed 攒 1.5s
+ * 就排一批（回合中写完马上 near 它/read_board 都要看得见 —— 惰性到回合末只修
+ * 一半病）；run 收尾再冲一次兜底（防抖窗口里挂掉的尾巴）。
+ */
+const FLUSH_MS = 1500;
+
+export function attachBoardSeater(bus, projectId) {
+  const pending = new Set();
+  let timer = null;
+  const flush = async () => {
+    if (timer) { clearTimeout(timer); timer = null; }
+    if (!pending.size) return;
+    const batch = [...pending]; pending.clear();
+    try {
+      const { seated, shelved } = await seatArtifacts(projectId, batch);
+      // 上架的要出声：架不是版面，agent 得给它们找地方（状态块每回合也点名）
+      if (seated) {
+        bus.publish({ type: 'board.updated', sessionId: null,
+          summary: `${seated} 件新产物入了座${shelved ? `（${shelved} 件在暂存架等安置）` : ''}` });
+      }
+    } catch (err) {
+      console.warn('[board-seater]', projectId, err?.message || err);
+    }
+  };
+  bus.subscribe('*', (evt) => {
+    if (!evt?.runId) return;
+    if (evt.type === 'run.file_changed') {
+      // 两种历史载荷形状都认（Events.fileChanged 的 filePath / 旧内联对象的 path）
+      const rel = typeof evt.filePath === 'string' ? evt.filePath : (typeof evt.path === 'string' ? evt.path : null);
+      if (!rel || !seatable(rel)) return;
+      pending.add(rel);
+      if (!timer) timer = setTimeout(flush, FLUSH_MS);
+      return;
+    }
+    if (evt.type === 'run.done' || evt.type === 'run.cancelled' || evt.type === 'run.error') void flush();
+  });
+}

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

@@ -3,34 +3,55 @@
  *
  * 用户定的文化：板书是基础设施。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。
+ * 这件事**由 harness 做，不靠 agent 记得**。
+ *
+ * ## 2026-08-30 改版：一个项目一张，可更新的版面组件
+ *
+ * 原来一轮（runId）一张便签，真板实证（proj_mtfz7n8p）：同一场会话两轮就两张
+ * 几乎一样的「步骤」，服务端一重启在内存的台账也丢，下一轮又新建 —— 板上全是
+ * 步骤便签的尸体。站主拍板改成**项目单例**：
+ *   - run.todo.updated → 全项目共用一张 `notes/板书/<stamp>-步骤.md`（tag=步骤），
+ *     内容原地重写；内存台账丢了就按 tag 从板上**认领旧的**，不再新建
+ *   - 首次落位上暂存架（seat:'shelf'，机器的手只够得到架）；agent/用户挪过之后
+ *     位置跨轮保留 —— 它就是一块可以被 edit_board move 经营的版面组件
+ *   - run.file_changed（有"正在"的步骤时）→ 便签到那件产物的 annotates 线，
+ *     label「第 N 步」，by:'auto'
+ *   - run.done/cancelled/error → **拆掉这一轮拉出去的 auto 步骤线**（线说的是
+ *     "正在其上工作"，工完线收；便签本身留着）
+ * 并发的轮各自记账、渲染时拼在同一张上（峰值并发 4，罕见且下一次更新就纠正）。
+ * 挂在 project bus 上；失败一律吞掉只 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 { layerOf, normalizeCanvasId } from '../../lib/canvas-id.js';
+import { textBox } from '../../lib/sketch-layout.js';
+import { resolveShelfOrigin, nextShelfSpot } from '../../lib/board-shelf.js';
 import { renderChalk, writeChalkFile, CHALK_DIR } from '../../lib/chalk.js';
 
-const byRun = new Map();   // runId → { projectId, rel, fileName, items, linked:Set, session }
+const TAG = '步骤';
+const byProject = new Map();   // projectId → { rel, fileName, runs: Map(runId → {items, linked:Set, session}) }
 const MAX_LINKS_PER_RUN = 24;
 
-function renderList(items) {
-  const lines = ['### 这一轮的步骤', ''];
+function renderItems(items) {
+  const out = [];
   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}`);
+    if (it.status === 'completed') out.push(`- [x] ${text}`);
+    else if (it.status === 'in_progress') out.push(`- [ ] **→ ${it.activeForm || text}**`);
+    else out.push(`- [ ] ${text}`);
+  });
+  return out;
+}
+
+function renderList(runs) {
+  const lines = ['### 这一轮的步骤', ''];
+  const active = [...runs.values()].filter(r => r.items.length);
+  active.forEach((r, idx) => {
+    if (idx > 0) lines.push('');   // 并发的轮拼在同一张上，段间空行分隔
+    lines.push(...renderItems(r.items));
   });
   return lines.join('\n');
 }
@@ -53,73 +74,94 @@ export function canvasIdForRel(board, rel) {
   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);
+/** 内存台账丢了（重启）就按 tag 从板上认领旧便签 —— 这是"不再新建"的另一半 */
+function adoptExisting(st, board) {
+  if (st.rel) return;
+  const hits = Object.entries(board.objects || {})
+    .filter(([id, e]) => id.startsWith(`${CHALK_DIR}/`) && e?.by === 'agent'
+      && typeof e?.tag === 'string' && (e.tag === TAG || e.tag.startsWith(`${TAG}-`)))
+    .map(([id]) => id)
+    .sort();
+  if (hits.length) { st.rel = hits[hits.length - 1]; st.fileName = st.rel.split('/').pop(); }
+}
+
+async function upsert(st, projectId, session) {
+  const body = renderList(st.runs);
+  const content = renderChalk({ body, by: 'agent', tag: TAG, sessionId: session || null });
+  const sharedRoot = getSharedDir(projectId);
+  const board = await readBoard(projectId);
+  adoptExisting(st, board);
   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 } } });
+    // 已有座位：只改高（行数变了）不碰宽/位置 —— 宽由前端量过真值，位置是
+    // agent/用户经营出来的，跨轮保留（可更新的版面组件正是这个意思）
+    await patchBoard(projectId, { objects: { [st.rel]: { ...prev, h: box.h, tag: TAG } } });
     return;
   }
-  // 首次落位：用户视口的空地 > 内容底下（跟 write_on_board 同口径）
+  // 首次落位（2026-08-30 暂存架）：机器的手只够得到架
   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 } } });
+  const vp = getViewpoint(projectId);
+  const origin = resolveShelfOrigin(board, (vp?.camera && !vp.layer) ? vp.camera : null);
+  const spot = nextShelfSpot(origin, obstacles);
+  await patchBoard(projectId, {
+    objects: { [st.rel]: { x: spot.x, y: spot.y, z: 1, w: box.w, h: box.h, by: 'agent', seat: 'shelf', tag: TAG } },
+    ...(origin.changed ? { shelf: { x: origin.x, y: origin.y } } : {}),
+  });
 }
 
 export function attachBoardTasklist(bus, projectId) {
   const handle = async (evt) => {
     if (!evt?.runId) return;
+    let st = byProject.get(projectId);
     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);
+      if (!st) { st = { rel: null, fileName: null, runs: new Map() }; byProject.set(projectId, st); }
+      let run = st.runs.get(evt.runId);
+      if (!run) { run = { items: [], linked: new Set(), session: evt.sessionId || null }; st.runs.set(evt.runId, run); }
+      run.items = items;
+      await upsert(st, projectId, run.session);
       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');
+      const run = st?.runs?.get(evt.runId);
+      if (!st?.rel || !run || !evt.filePath) return;
+      const idx = run.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);
+      if (run.linked.size >= MAX_LINKS_PER_RUN) return;
+      const board = await readBoard(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 } } });
+      if (run.linked.has(target)) return;
+      run.linked.add(target);
+      const id = `b:auto:step:${String(evt.runId).slice(-6)}:${run.linked.size}`;
+      await patchBoard(projectId, { bindings: { [id]: { type: 'annotates', from: st.rel, to: target, by: 'auto', label: `第 ${idx + 1} 步`, tag: 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);
+      const run = st?.runs?.get(evt.runId);
+      if (!run) return;
+      st.runs.delete(evt.runId);
+      // 工完线收：这一轮拉出去的 auto 步骤线说的是"正在其上工作"，轮结束就拆
+      if (run.linked.size) {
+        const dead = {};
+        for (let n = 1; n <= run.linked.size; n += 1) dead[`b:auto:step:${String(evt.runId).slice(-6)}:${n}`] = null;
+        await patchBoard(projectId, { bindings: dead });
+      }
     }
   };
   bus.subscribe('*', (evt) => {
@@ -127,4 +169,4 @@ export function attachBoardTasklist(bus, projectId) {
   });
 }
 
-export function _resetBoardTasklist() { byRun.clear(); }
+export function _resetBoardTasklist() { byProject.clear(); }

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

@@ -193,8 +193,8 @@ export function getQueueDepth(sessionId) {
  * 回显到了一条排队消息、而 turn 正在跑 = CLI 把它并进了当前轮。它的 run 行不能
  * 停在 pending（那就是老病：runs 表里"排队 N 分钟"的假象），也不能等一个永远不来
  * 的 result。就地 running→succeeded，metadata 记它并进了谁；token/费用全记在承载它
- * 的那一轮（SDK 的 result 本来就只给一份）。run.merged 事件给前端/审计看，前端
- * 现在不消费（追加那条从没被认领过 runId，不需要清状态）。
+ * 的那一轮（SDK 的 result 本来就只给一份）。run.merged 事件给前端/审计看 ——
+ * 前端 08-28 起消费（aux-events.js 弹一条「并进了正在跑的回合」）。
  */
 export function closeMergedRun({ runId, intoRunId, sessionId, sdkSessionId, eventBus }) {
   try { markRunStarted(runId); } catch { /* 不该已 running；兜底继续关 */ }
@@ -215,3 +215,25 @@ export function closeMergedRun({ runId, intoRunId, sessionId, sdkSessionId, even
 export function publishQueueDepth(eventBus, sessionId) {
   eventBus.publish({ type: 'run.queue.depth', sessionId, depth: getQueueDepth(sessionId), ts: new Date().toISOString() });
 }
+
+/**
+ * 这条 SDK 消息算不算「自发了一个没主的回合」（session-loop 据此 mintBackgroundTurn）。
+ *
+ * ⛔ **子代理说话不算**（2026-08-26 用户真机复现）：判据原来只看 type，于是常驻角色
+ * 被用户的直达消息唤醒、开口第一句时就铸出一个主回合并 emit run.start。而那个 run
+ * **永远收不了** —— 角色跑的是子代理回合，不会有主循环的 result，finishTurn /
+ * releaseCurrentTurnRunId 都轮不到。连锁四个症状：
+ *   1. 侧栏按钮变「停止」，用户以为对话被占用
+ *   2. currentTurnRunId 挂死 → 每次重连 ws 的 activeRunId 又把「停止」确认一遍，回不去
+ *   3. 点「停止」= cancel 那个铸出来的 run → SDK abort 把**在飞的其他角色一起杀了**
+ *   4. 时间轴上多一条永远转的圈
+ *
+ * 后台自发回合这条路本身是对的（task_notification 唤起主代理时确实没主），
+ * 它只是分不出「主代理醒了」和「子代理说话了」—— 用 parent_tool_use_id 分。
+ */
+export function isBackgroundTurnOpener(message) {
+  if (message?.parent_tool_use_id) return false;
+  return message?.type === 'assistant'
+    || message?.type === 'stream_event'
+    || message?.type === 'user';
+}

package/server/engine/runs/user-chalk-echo.js

@@ -0,0 +1,44 @@
+/**
+ * server/engine/runs/user-chalk-echo.js —— 用户说话的落痕（2026-08-27 solo 画布对话）
+ *
+ * 用户从画布标注「说给某个角色」时，话直投收件箱（role-direct 那条 08-26 的路），
+ * 但板上什么都不留 —— 这条对话线于是只有角色那半声道，事后回看像一出只印了
+ * 一半台词的剧本。这里把同一句话落成 by:'user' 的板书接进线：
+ *
+ *   - 标注的目标是板书 → frontmatter reply_to 它（线程接上，flow 线照领养同款画）
+ *   - 目标是别的画布物件 → frontmatter anchor 它（annotates 线）
+ *   - tag 继承目标的（同一条戏线）
+ *
+ * 落座直接复用板书领养（board-seater.seatArtifacts）：say 端点不是 run，没有
+ * run.file_changed 事件可搭，得当场调。
+ *
+ * ⚠️ 调用方约定：落痕失败**不拦投递** —— 话必须送到，痕是锦上添花。这里抛出的
+ * 错由调用方吞并降级（照常 deliver，不带 echo 指针）。
+ */
+
+import { readBoard } from '../../projects/board-store.js';
+import { getSharedDir } from '../../projects/workspace.js';
+import { normalizeCanvasId } from '../../lib/canvas-id.js';
+import { renderChalk, chalkFileName, writeChalkFile, CHALK_DIR } from '../../lib/chalk.js';
+import { seatArtifacts } from './board-seater.js';
+
+/**
+ * @param {string} projectId
+ * @param {{ text: string, anchor?: string|null }} p  anchor = 标注目标的 canvas id
+ * @returns {Promise<{ rel: string, seated: boolean }>} rel = 落下的板书相对路径
+ */
+export async function echoUserChalk(projectId, { text, anchor = null }) {
+  const board = await readBoard(projectId);
+  const aid = anchor ? normalizeCanvasId(String(anchor).slice(0, 300)) : null;
+  const ae = aid ? board.objects?.[aid] : null;
+  const isChalk = !!(ae && aid.startsWith(`${CHALK_DIR}/`));
+  const content = renderChalk({
+    body: text, by: 'user',
+    // 目标不在板上就落成无链板书（还是比丢掉这半段对话强）
+    ...(ae ? (isChalk ? { replyTo: aid } : { anchor: aid }) : {}),
+    ...(ae?.tag ? { tag: ae.tag } : {}),
+  });
+  const rel = await writeChalkFile(getSharedDir(projectId), chalkFileName(text), content);
+  const { seated } = await seatArtifacts(projectId, [rel]);
+  return { rel, seated: seated > 0 };
+}

package/server/index.js

@@ -33,8 +33,8 @@ import turnRouter from './api/turn.js';
 import exportsRouter from './api/exports.js';
 import sessionsRouter from './api/sessions.js';
 import instructionRouter from './api/instruction.js';
-import memoryRouter from './api/memory.js';
 import boardRouter from './api/board.js';
+import stageRouter from './api/stage.js';
 import pendingChangesRouter from './api/pending-changes.js';
 import browseRouter from './api/browse.js';
 import publishRouter from './api/publish.js';
@@ -118,8 +118,8 @@ app.use('/api/projects', turnRouter);
 app.use('/api/projects', exportsRouter);
 app.use('/api/projects', sessionsRouter);
 app.use('/api/projects', instructionRouter);
-app.use('/api/projects', memoryRouter);
 app.use('/api/projects', boardRouter);
+app.use('/api/projects', stageRouter);        // 用户从画布对角色说的话落在画布上
 app.use('/api/projects', pendingChangesRouter);  // C4: 用户直接编辑 + 评论 buffer
 app.use('/api/projects', browseRouter);          // 刷新后拿回浏览器窗/求助状态
 app.use('/api/projects', publishRouter);         // 站点一键上线 Cloudflare Pages