@baique/pi-web-sky 0.1.39 → 0.1.40

package/lib/board-reconcile.ts

@@ -0,0 +1,422 @@
+// ============================================================================
+// 看板派生 reconcile（后端权威）—— 替代前端 useBoardCanvas 的 reconcile
+//
+// 设计（方案 rev2 核心）：
+//   - 业务表（tasks / task_cards / task_card_links / session_meta）= 唯一真相源，后端写
+//   - 派生元素（会话卡存在性 / exec 线 / 依赖线 / 孤儿删）= 后端读业务表 → 增量写 Y.Doc
+//   - 确定性 id 幂等：会话卡 `session-<sid>`、exec 线 `exec-<cardId>-<sessionId>`、
+//     依赖线 `link-<fromShapeId>-<toShapeId>-<kind>` → 缺补多删，绝不整表覆盖
+//   - 用户内容（布局/尺寸/便笺文本）由前端写 Y.Doc，本模块只动派生元素，不碰用户布局
+//   - 孤儿删只删「业务表确认不存在的会话卡」，跳过新会话卡（cwd 非空 = 会话尚未创建）
+//
+// 触发：调度器写业务表后 / 任务归属变化 / 建卡删卡 / 定时兜底（见 board-reconcile-scheduler）
+// ============================================================================
+import { getBoard, listAllBoards } from "./board-store";
+import { listTaskSessionIds } from "./task-store";
+import { listCards, listLinks } from "./task-card-store";
+
+// ---- yjs maps 类型 + mutateBoard（由 server.mjs 通过 globalThis 注入，避免 Next 打包 node:sqlite）----
+interface BoardMaps {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- yjs Map 泛型在服务端宽松处理（避免过度类型工程）
+  nodes: import("yjs").Map<any>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  edges: import("yjs").Map<any>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  view: import("yjs").Map<any>;
+  ydoc: import("yjs").Doc;
+}
+
+declare global {
+  var __yjsBoard: {
+    mutateBoard: (boardId: string, transaction: (maps: BoardMaps) => void) => Promise<unknown>;
+    destroyBoardDocument: (boardId: string) => Promise<void>;
+  } | undefined;
+}
+
+const mutateBoard: (boardId: string, transaction: (maps: BoardMaps) => void) => Promise<unknown> =
+  ((boardId: string, transaction: (maps: BoardMaps) => void) => {
+    const yjs = globalThis.__yjsBoard;
+    if (!yjs) return Promise.resolve(); // server.mjs 未加载（独立构建/测试环境）→ 跳过
+    return yjs.mutateBoard(boardId, transaction);
+  });
+
+/** Y.Doc 节点（RF Node 形状的宽松类型） */
+interface DocNode {
+  id: string;
+  type?: string;
+  position?: { x: number; y: number };
+  style?: { width?: number; height?: number };
+  data?: Record<string, unknown>;
+}
+
+
+// ---- 卡片尺寸（与前端组件对齐，作补卡摆位锚点）----
+export const CARD_W = 340;
+export const CARD_H = 160;
+const FORM_W = 380;
+const COLLAPSED_MIN_H = 240;
+
+/** 会话卡默认尺寸（收合态） */
+export const SESSION_CARD_W = CARD_W;
+export const SESSION_CARD_H = CARD_H;
+
+/** 任务卡 shape 尺寸（未建卡占位 / 已建卡） */
+const TASK_CARD_W = FORM_W;
+const TASK_CARD_H = COLLAPSED_MIN_H;
+
+/** 判断 Y.Doc 中某节点是否为「新会话卡」（cwd 非空 = 会话尚未创建，跳过补卡/孤儿删） */
+function isPendingNewSession(node: DocNode | undefined): boolean {
+  const cwd = node?.data?.cwd;
+  return Boolean(node && typeof cwd === "string" && cwd.length > 0);
+}
+
+/** 找空闲落点（4 列布局：每行 4 卡，逐行找空位）。与前端 findFreeSpot 同构。 */
+function findFreeSpot(nodes: DocNode[], width = CARD_W, height = CARD_H) {
+  const STEP = 24;
+  const PER_ROW = 4;
+  const occupied = nodes
+    .filter((n) => n?.type === "session-card")
+    .map((n) => ({
+      x: n.position?.x ?? 0,
+      y: n.position?.y ?? 0,
+      w: n.style?.width ?? width,
+      h: n.style?.height ?? height,
+    }));
+  const overlaps = (x: number, y: number) =>
+    occupied.some((o) => x < o.x + o.w + STEP && x + width + STEP > o.x && y < o.y + o.h + STEP && y + height + STEP > o.y);
+  let y = 60;
+  let guard = 0;
+  while (guard < 2000) {
+    for (let col = 0; col < PER_ROW; col += 1) {
+      const x = 60 + col * (width + STEP);
+      if (!overlaps(x, y)) return { x, y };
+    }
+    y += height + STEP;
+    guard += 1;
+  }
+  return { x: 60, y: 60 };
+}
+
+/**
+ * 对单个看板执行派生 reconcile（幂等）。
+ * 读业务表 → mutate Y.Doc：补/清会话卡、补/清 exec 线、补/清依赖线。
+ * 仅任务看板（board.taskId 非空）有派生元素；普通看板跳过。
+ */
+export async function reconcileBoard(boardId: string): Promise<void> {
+  const board = getBoard(boardId);
+  if (!board?.taskId) return; // 普通看板：会话卡由用户拖入/新建管理，无派生
+  const taskId = board.taskId;
+
+  const sessionIds = listTaskSessionIds(taskId);
+  const cards = listCards(boardId);
+  // 全部会话 id（任务会话 + 任务卡执行会话）——执行会话卡必然存在（先有会话才有关联）
+  const allSessionIds = new Set(sessionIds);
+  for (const c of cards) if (c.sessionId) allSessionIds.add(c.sessionId);
+
+  await mutateBoard(boardId, (maps) => {
+    const nodesMap = maps.nodes;
+    const edgesMap = maps.edges;
+    const nodes = Array.from(nodesMap.values()) as unknown as DocNode[];
+
+    // ---- 1) 会话卡：缺补、孤儿删 ----
+    const existingSessionBySid = new Map(); // sid -> node（转正卡）
+    const pendingSids = new Set(); // 新建中占位卡（cwd 非空）的 sid——视为「该 sid 已有卡，不补、不孤儿删」
+    for (const n of nodes) {
+      if (n?.type !== "session-card") continue;
+      const sid = n.data?.sessionId;
+      if (!sid) continue;
+      // 新建中占位卡（cwd 非空）：不参与转正卡 map，也不做孤儿删；
+      // 但它的 sid 要进 pendingSids——窗口期（服务端已 assign、前端尚未转正清 cwd）
+      // 补卡循环应把该 sid 视为「已覆盖」，否则会补出第二张确定性 session-<sid> 卡。
+      if (isPendingNewSession(n)) {
+        pendingSids.add(sid);
+        continue;
+      }
+      existingSessionBySid.set(sid, n);
+    }
+    // 孤儿删：画布有、业务表没有的会话卡（非新会话卡）→ 删
+    // 例外：卡声明归属本板任务（data.taskId === 本板 taskId，拖入已存在会话时前端先落卡
+    // 异步归属，归属完成前本板 reconcile 不能把它当孤儿删——否则用户刚拖的卡消失）
+    const orphanIds = [];
+    for (const [sid, n] of existingSessionBySid) {
+      if (allSessionIds.has(sid)) continue;
+      if (n.data?.taskId === taskId) continue;
+      orphanIds.push(n.id);
+    }
+    for (const id of orphanIds) {
+      nodesMap.delete(id);
+      // 级联删以它为端点的边（exec/依赖/手绘线）
+      for (const e of Array.from(edgesMap.values())) {
+        if (e.source === id || e.target === id) edgesMap.delete(e.id);
+      }
+    }
+    // 缺卡补：业务表有、画布没有的会话卡 → 补（确定性 id，4 列布局落点）
+    // 补全 allSessionIds（任务根会话 + 任务卡执行会话）——exec 线目标会话卡必须有节点。
+    // 注意：不能因画布存在「新建中占位卡」（pendingNew，cwd 非空）就跳过补卡——
+    // 那会让任务卡执行会话卡永远不补、exec 线断（历史 bug）。补卡 id 为确定性 session-<sid>，
+    // 与随机 id 的占位卡不冲突、幂等。
+    {
+      const remaining = Array.from(nodesMap.values());
+      for (const sid of allSessionIds) {
+        // 已有转正卡 或 存在同 sid 新建中占位卡（窗口期视为已覆盖）→ 不补
+        if (existingSessionBySid.has(sid) || pendingSids.has(sid)) continue;
+        const id = `session-${sid}`;
+        const spot = findFreeSpot(remaining);
+        nodesMap.set(id, {
+          id,
+          type: "session-card",
+          position: { x: spot.x, y: spot.y },
+          style: { width: SESSION_CARD_W, height: SESSION_CARD_H },
+          data: {
+            sessionId: sid,
+            title: "",
+            projectName: "",
+            messageCount: 0,
+            lastReply: "",
+            phase: "idle",
+            runningMs: 0,
+            endedAt: 0,
+            lastActivityAt: 0,
+            stale: false,
+            expanded: false,
+            cwd: "",
+            taskId: "",
+            w: SESSION_CARD_W,
+            h: SESSION_CARD_H,
+            expandedW: 0,
+            expandedH: 0,
+            collapsedW: 0,
+            collapsedH: 0,
+          },
+        });
+        remaining.push(nodesMap.get(id));
+      }
+    }
+
+    // ---- 1.5) 任务卡节点补齐：业务表存在、画布无对应节点 → 补（exec 线锚点）----
+    // 任务卡由用户从工具栏拖出创建；业务表已存在的卡（外部建卡/历史数据）自动入板。
+    // 确定性 id（task-<cardId>）→ 幂等；孤儿任务卡节点（业务表已删）→ 删。
+    const existingCardByCardId = new Map(); // cardId -> node
+    for (const n of nodes) {
+      if (n?.type === "task-card" && n.data?.cardId) existingCardByCardId.set(n.data.cardId, n);
+    }
+    // 孤儿任务卡：画布有 cardId 但业务表没有 → 删节点（级联删边）
+    const knownCardIds = new Set(cards.map((c) => c.id));
+    const orphanCardIds = [];
+    for (const [cid, n] of existingCardByCardId) {
+      if (!knownCardIds.has(cid)) orphanCardIds.push(n.id);
+    }
+    for (const id of orphanCardIds) {
+      nodesMap.delete(id);
+      for (const e of Array.from(edgesMap.values())) {
+        if (e.source === id || e.target === id) edgesMap.delete(e.id);
+      }
+    }
+    // 缺卡补：业务表有、画布没有 → 补（form 尺寸，4 列布局）
+    {
+      const remaining = Array.from(nodesMap.values()) as unknown as DocNode[];
+      for (const card of cards) {
+        if (existingCardByCardId.has(card.id)) continue;
+        const id = `task-${card.id}`;
+        const spot = findFreeSpot(remaining, TASK_CARD_W, TASK_CARD_H);
+        nodesMap.set(id, {
+          id,
+          type: "task-card",
+          position: { x: spot.x, y: spot.y },
+          style: { width: TASK_CARD_W, height: TASK_CARD_H },
+          data: {
+            cardId: card.id,
+            number: card.number,
+            name: card.name,
+            description: card.description,
+            readyStatus: card.readyStatus,
+            execStatus: card.execStatus,
+            priority: card.priority,
+            due: card.due ?? undefined,
+            expanded: false,
+            w: TASK_CARD_W,
+            h: TASK_CARD_H,
+            expandedW: 0,
+            expandedH: 0,
+            collapsedW: 0,
+            collapsedH: 0,
+          },
+        });
+        remaining.push(nodesMap.get(id));
+      }
+    }
+
+    // ---- 2) exec 线：任务卡 sessionId → 卡节点 + 会话节点 → 建线 ----
+    // 卡 shape：cardId 映射到节点
+    const cardShapes = new Map(); // cardId -> node
+    for (const n of Array.from(nodesMap.values()) as unknown as DocNode[]) {
+      if (n?.type === "task-card" && n.data?.cardId) cardShapes.set(n.data.cardId, n);
+    }
+    const sessionShapes = new Map(); // sid -> node（含刚补的）
+    for (const n of Array.from(nodesMap.values())) {
+      if (n?.type === "session-card" && n.data?.sessionId) sessionShapes.set(n.data.sessionId, n);
+    }
+    // 现有 exec 线按 from 卡节点分组
+    const execByCard = new Map<string, Array<{ to: string | null; edgeId: string }>>(); // fromShapeId -> [{ to, edgeId }]
+    for (const e of Array.from(edgesMap.values())) {
+      if (!e.data?.execLink) continue;
+      const from = e.source;
+      const list = execByCard.get(from) ?? [];
+      list.push({ to: e.target, edgeId: e.id });
+      execByCard.set(from, list);
+    }
+    for (const card of cards) {
+      const cardShape = cardShapes.get(card.id);
+      if (!cardShape) continue;
+      const wanted = card.sessionId ? sessionShapes.get(card.sessionId) : null;
+      const existing = execByCard.get(cardShape.id) ?? [];
+      // 删端点不匹配的旧线（卡 sessionId 变了 / 已清空）
+      for (const e of existing) {
+        if (e.to !== (wanted?.id ?? null)) edgesMap.delete(e.edgeId);
+      }
+      if (!wanted || existing.some((e) => e.to === wanted.id)) continue;
+      const id = `exec-${card.id}-${card.sessionId}`;
+      edgesMap.set(id, {
+        id,
+        source: cardShape.id,
+        target: wanted.id,
+        type: "default",
+        data: { execLink: true, cardId: card.id, sessionId: card.sessionId },
+        markerEnd: { type: "arrowclosed" },
+        style: { strokeWidth: 1.5, stroke: "#3184f8", strokeDasharray: "6 4" },
+      });
+    }
+
+    // ---- 3) 依赖线：task_card_links → 建线（缺补多删）----
+    const existingLinks = new Map(); // "<from>-><to>:<kind>" -> edgeId
+    for (const e of Array.from(edgesMap.values())) {
+      if (!e.data?.taskLink) continue;
+      const from = e.source;
+      const to = e.target;
+      const kind = e.data.taskLink;
+      if (from && to && kind) existingLinks.set(`${from}->${to}:${kind}`, e.id);
+    }
+    const wantLinks = new Set();
+    for (const card of cards) {
+      const fromShape = cardShapes.get(card.id);
+      if (!fromShape) continue;
+      for (const link of listLinks(card.id)) {
+        const toShape = cardShapes.get(link.targetCardId);
+        if (!toShape) continue;
+        const key = `${fromShape.id}->${toShape.id}:${link.kind}`;
+        wantLinks.add(key);
+        if (!existingLinks.has(key)) {
+          const id = `link-${fromShape.id}-${toShape.id}-${link.kind}`;
+          edgesMap.set(id, {
+            id,
+            source: fromShape.id,
+            target: toShape.id,
+            type: "default",
+            data: { taskLink: link.kind },
+            markerEnd: { type: "arrowclosed" },
+            style: { strokeWidth: 1.5, stroke: "#f59e0b" },
+          });
+        }
+      }
+    }
+    for (const [key, edgeId] of existingLinks) {
+      if (!wantLinks.has(key)) edgesMap.delete(edgeId);
+    }
+  });
+}
+
+/**
+ * 任务下新建的会话入板（需求 2：外部/本页新建会话自动加入任务看板）。
+ * 调度器 assignSessionToTask 后调用：补一张会话卡到对应任务看板。
+ * 幂等（确定性 id）；看板不存在（任务看板未创建）时静默跳过。
+ */
+export async function ensureTaskSessionCard(boardId: string, sessionId: string): Promise<void> {
+  const board = getBoard(boardId);
+  if (!board?.taskId) return;
+  await mutateBoard(boardId, (maps) => {
+    const nodesMap = maps.nodes;
+    const nodes = Array.from(nodesMap.values());
+    const id = `session-${sessionId}`;
+    if (nodesMap.has(id)) return;
+    const spot = findFreeSpot(nodes);
+    nodesMap.set(id, {
+      id,
+      type: "session-card",
+      position: { x: spot.x, y: spot.y },
+      style: { width: SESSION_CARD_W, height: SESSION_CARD_H },
+      data: {
+        sessionId,
+        title: "",
+        projectName: "",
+        messageCount: 0,
+        lastReply: "",
+        phase: "idle",
+        runningMs: 0,
+        endedAt: 0,
+        lastActivityAt: 0,
+        stale: false,
+        expanded: false,
+        cwd: "",
+        taskId: "",
+        w: SESSION_CARD_W,
+        h: SESSION_CARD_H,
+        expandedW: 0,
+        expandedH: 0,
+        collapsedW: 0,
+        collapsedH: 0,
+      },
+    });
+  });
+}
+
+/**
+ * 从所有 RF 看板的 yjs 文档中删除指定会话的会话卡（含占位卡）并级联删边。
+ *
+ * 背景：会话删除（单删 / 删任务整树）只走 removeSessionFromBoards 清 tldraw 遗留的
+ * board_nodes 废弃表，对 RF 画布（yjs Y.Doc）无效——任务看板由 10s reconcile 兜底删，
+ * 普通看板 reconcileBoard 直接 return，会话卡永久残留（幽灵卡）。
+ *
+ * 定位：会话卡落在哪块看板没有反向索引，只能枚举全部看板逐个扫（低频操作可接受；
+ * 维护反向索引属过度设计）。幂等：板上没有匹配卡时无变更。
+ */
+export async function removeSessionsFromYjsBoards(sessionIds: string[]): Promise<void> {
+  if (sessionIds.length === 0) return;
+  const yjs = globalThis.__yjsBoard;
+  if (!yjs) return; // server.mjs 未加载（独立构建/测试环境）→ 跳过
+  const targets = new Set(sessionIds);
+  for (const board of listAllBoards()) {
+    try {
+      await yjs.mutateBoard(board.id, (maps) => {
+        const nodesMap = maps.nodes;
+        const edgesMap = maps.edges;
+        const hitIds: string[] = [];
+        for (const n of Array.from(nodesMap.values()) as unknown as DocNode[]) {
+          if (n?.type === "session-card" && n.data?.sessionId && targets.has(String(n.data.sessionId))) {
+            hitIds.push(n.id);
+          }
+        }
+        if (hitIds.length === 0) return;
+        for (const id of hitIds) {
+          nodesMap.delete(id);
+          for (const e of Array.from(edgesMap.values())) {
+            if (e.source === id || e.target === id) edgesMap.delete(e.id);
+          }
+        }
+      });
+    } catch (e) {
+      // 单板清理失败不中断其余板（也绝不拖垮会话删除主流程）
+      console.warn(`[board] 会话删除清理 yjs 板 ${board.id} 异常:`, e instanceof Error ? e.message : e);
+    }
+  }
+}
+
+/**
+ * 删除看板的 yjs 文档（业务行删完后调用）。
+ * deleteBoard/deleteTask 只清 boards/board_nodes 等业务表，yjs_documents 行残留会导致
+ * 看板 id 复用时旧文档复活；此处同时断开该看板的活动连接。
+ */
+export async function destroyBoardYjsDocument(boardId: string): Promise<void> {
+  const yjs = globalThis.__yjsBoard;
+  if (!yjs) return;
+  await yjs.destroyBoardDocument(boardId);
+}

package/lib/board-store.test.mjs

@@ -8,6 +8,7 @@ const { setDbForTesting, SCHEMA_VERSION } = await jiti.import("./sqlite-db.ts");
 const {
   getBoard,
   listBoards,
+  listAllBoards,
   createBoard,
   renameBoard,
   deleteBoard,
@@ -25,6 +26,7 @@ const {
   deleteEdge,
   getSystemRunningBoard,
   reorderBoards,
+  reorderAllBoards,
   syncCardEdges,
   syncExecEdge,
   removeSessionFromBoards,
@@ -56,9 +58,9 @@ test("schema version reaches latest with board tables", () => {
     .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'boards'")
     .all();
   assert.equal(boards.length, 1);
-  assert.equal(SCHEMA_VERSION, 8);
+  assert.equal(SCHEMA_VERSION, 9);
   const row = db.prepare("PRAGMA user_version").get();
-  assert.equal(row.user_version, 8);
+  assert.equal(row.user_version, 9);
   // v5 迁移：boards.task_id 列存在
   const cols = db.prepare("PRAGMA table_info(boards)").all().map((c) => c.name);
   assert.ok(cols.includes("task_id"));
@@ -87,11 +89,31 @@ test("board CRUD: create / rename / list / delete", () => {
   assert.equal(listBoards(PROJECT).length, 0);
 });
 
-test("empty projectKey / name rejected", () => {
-  assert.throws(() => createBoard("", "x"), /projectKey is required/);
+test("empty projectKey creates global board / empty name rejected", () => {
+  // 空 projectKey 现为全局共享看板（跨项目聚合，与系统看板同层语义）
+  const g = createBoard("", "全局板");
+  assert.equal(g.projectKey, "");
+  assert.equal(g.isSystem, false);
+  assert.equal(g.taskId, null);
   assert.throws(() => createBoard(PROJECT, "  "), /name must not be empty/);
 });
 
+test("global boards: listAllBoards aggregates across projects + reorderAllBoards", () => {
+  const pa = createBoard("proj-a", "A");
+  const pb = createBoard("proj-b", "B");
+  const g = createBoard("", "G");
+  // 全局列表含所有项目 + 全局看板（新板置顶：G 取全局最小 -1 最前，A/B 同项目内 sort 0 按 created）
+  assert.deepEqual(listAllBoards().map((x) => x.id), [g.id, pa.id, pb.id]);
+
+  // 全局排序跨项目
+  const reordered = reorderAllBoards([pa.id, g.id, pb.id]);
+  assert.deepEqual(reordered.map((x) => x.id), [pa.id, g.id, pb.id]);
+
+  // 外来 id（含任务型/系统）→ 回滚保持原序
+  assert.throws(() => reorderAllBoards([pa.id, "foreign"]));
+  assert.deepEqual(listAllBoards().map((x) => x.id), [pa.id, g.id, pb.id]);
+});
+
 test("system running board: always present, not deletable/renamable", () => {
   const sys = getSystemRunningBoard();
   assert.equal(sys.id, SYSTEM_RUNNING_BOARD_ID);

package/lib/board-store.ts

@@ -182,6 +182,19 @@ export function listBoards(projectKey: string): BoardInfo[] {
   return rows.map((row) => rowToBoard(row, countNodes(row.id)));
 }
 
+/**
+ * 全部看板（不含系统看板，系统看板由调用方前置插入）。全局共享视图：
+ * 不看 project_key，所有手动看板 + 任务型看板一起返回（展示层自行过滤 taskId）。
+ */
+export function listAllBoards(): BoardInfo[] {
+  const rows = getDb()
+    .prepare(
+      "SELECT id, project_key AS projectKey, name, is_system AS isSystem, task_id AS taskId, sort_order AS sortOrder, created, updated FROM boards WHERE is_system = 0 ORDER BY sort_order, created, rowid",
+    )
+    .all() as unknown as BoardRow[];
+  return rows.map((row) => rowToBoard(row, countNodes(row.id)));
+}
+
 /**
  * 项目内看板批量排序（完整有序 id 列表）。id 必须都属于该项目，否则事务回滚。
  */
@@ -205,17 +218,42 @@ export function reorderBoards(projectKey: string, orderedIds: string[]): BoardIn
   return listBoards(projectKey);
 }
 
-/** 创建看板。空 projectKey / 空名抛错。taskId 可选：非空时看板为任务型（id = taskId）。 */
+/**
+ * 全局看板批量排序（完整有序 id 列表，手动看板范围：非系统、非任务型）。
+ * id 必须都存在且属于手动看板，否则事务回滚。
+ */
+export function reorderAllBoards(orderedIds: string[]): BoardInfo[] {
+  const db = getDb();
+  if (orderedIds.length === 0) return listAllBoards();
+  db.exec("BEGIN");
+  try {
+    const stmt = db.prepare("UPDATE boards SET sort_order = ?, updated = ? WHERE id = ? AND is_system = 0 AND task_id IS NULL");
+    orderedIds.forEach((id, index) => {
+      const res = stmt.run(index, now(), id);
+      if (res.changes === 0) {
+        throw new Error(`board ${id} does not belong to global manual scope`);
+      }
+    });
+    db.exec("COMMIT");
+  } catch (error) {
+    db.exec("ROLLBACK");
+    throw error;
+  }
+  return listAllBoards();
+}
+
+/** 创建看板。空 projectKey 表示全局共享看板（跨项目聚合，与系统看板同层）。
+ *  空名抛错。taskId 可选：非空时看板为任务型（id = taskId）。 */
 export function createBoard(projectKey: string, name: string, taskId?: string): BoardInfo {
   const trimmed = name.trim();
-  if (!projectKey) throw new Error("projectKey is required");
   if (!trimmed) throw new Error("name must not be empty");
   const id = taskId ?? randomUUID();
   const ts = now();
-  // 新看板置顶：sort_order 取当前项目最小值 - 1
-  const minRow = getDb()
-    .prepare("SELECT MIN(sort_order) AS minOrder FROM boards WHERE project_key = ?")
-    .get(projectKey) as { minOrder: number | null };
+  const global = !projectKey;
+  // 新看板置顶：全局看板取全部手动看板最小 - 1；项目看板取项目内最小 - 1
+  const minRow = global
+    ? (getDb().prepare("SELECT MIN(sort_order) AS minOrder FROM boards WHERE is_system = 0 AND task_id IS NULL").get() as { minOrder: number | null })
+    : (getDb().prepare("SELECT MIN(sort_order) AS minOrder FROM boards WHERE project_key = ?").get(projectKey) as { minOrder: number | null });
   const sortOrder = minRow.minOrder === null ? 0 : minRow.minOrder - 1;
   getDb()
     .prepare("INSERT INTO boards (id, project_key, name, is_system, task_id, sort_order, created, updated) VALUES (?, ?, ?, 0, ?, ?, ?, ?)")

package/lib/i18n/messages/en.ts

@@ -162,7 +162,7 @@ export const enLocale: LocalePlugin = {
     "boards.system": "System",
     "boards.title": "Boards",
     "boards.dragToAdd": "Drag sessions from the sidebar to add",
-    "boards.dropToAdd": "Drop to add session",
+    "boards.dropToAdd": "Drop to add to board",
     "boards.loadingSession": "Loading session…",
     "boards.sessionMissing": "Session no longer exists",
     "boards.collapse": "Collapse",

package/lib/i18n/messages/zh-CN.ts

@@ -163,7 +163,7 @@ export const zhCNLocale: LocalePlugin = {
     "boards.system": "系统",
     "boards.title": "看板",
     "boards.dragToAdd": "从侧栏拖入会话以添加",
-    "boards.dropToAdd": "松手添加会话",
+    "boards.dropToAdd": "松手添加到看板",
     "boards.loadingSession": "正在加载会话…",
     "boards.sessionMissing": "会话已不存在",
     "boards.collapse": "收合",

package/lib/session-delete.ts

@@ -15,6 +15,7 @@ import { sessionPathKey } from "./session-path";
 import { getRpcSession } from "./rpc-manager";
 import { unassignSession } from "./task-store";
 import { removeSessionFromBoards } from "./board-store";
+import { removeSessionsFromYjsBoards } from "./board-reconcile";
 
 /** 递归收集一个会话的全部 fork 后代 id（含自身）。 */
 export async function collectSessionDescendants(rootId: string): Promise<string[]> {
@@ -82,5 +83,9 @@ export async function deleteSessionTrees(rootIds: string[]): Promise<string[]> {
       } catch { /* keep deleting the rest */ }
     }
   }
+  // RF 画布（yjs）清理：从所有普通看板移除这些会话的卡（含占位卡）。
+  // 任务看板由删除方（deleteTask）整体销毁文档，这里一并处理也无害；
+  // 无 __yjsBoard（测试/独立构建）时为空操作。
+  await removeSessionsFromYjsBoards(deleted);
   return deleted;
 }

package/lib/sqlite-db.ts

@@ -88,7 +88,7 @@ export function initSchema(db: DatabaseSync): void {
  * 老库打开时自动按序补齐缺失的迁移（每个迁移一个事务，成功后推进版本号），
  * 新库建表后从 v0 一路迁到 SCHEMA_VERSION。重复打开不再执行已完成的迁移。
  */
-export const SCHEMA_VERSION = 8;
+export const SCHEMA_VERSION = 9;
 
 interface Migration {
   version: number;
@@ -175,6 +175,18 @@ const MIGRATIONS: Migration[] = [
       "ALTER TABLE task_cards ADD COLUMN dispatch_token TEXT NULL;",
     ],
   },
+  {
+    version: 9,
+    name: "task_cards.owner + heartbeat (状态判定实例归属)",
+    statements: [
+      // 多实例共库时，「会话是否在跑」是本进程私有（getRunningRpcSessionIds），
+      // 非派发实例会误把别人在跑的卡翻成 review（#27）。给 running 卡标 owner
+      // + heartbeat，非 owner 且 owner 心跳新鲜 → 跳过，只有 owner（或 owner
+      // 心跳过期被接管）才判定状态，使「谁判定某张卡」确定。
+      "ALTER TABLE task_cards ADD COLUMN owner TEXT NULL;",
+      "ALTER TABLE task_cards ADD COLUMN heartbeat INTEGER NOT NULL DEFAULT 0;",
+    ],
+  },
 ];
 
 function migrate(db: DatabaseSync): void {