@baique/pi-web-sky 0.1.39 → 0.1.41

package/lib/task-card-store.ts

@@ -43,6 +43,10 @@ export interface TaskCard {
   sessionId: string | null;
   /** 跨进程派发互斥 token：谁抢到谁执行（多实例共库防双会话） */
   dispatchToken: string | null;
+  /** 状态判定实例归属：派发/续会话时写入的实例 id；null=旧数据（任何实例可接管） */
+  owner: string | null;
+  /** 归属心跳（ms epoch）：owner 每 ~10s 刷新一次；过期视 owner 已死可接管 */
+  heartbeat: number;
   created: number;
   updated: number;
 }
@@ -73,6 +77,8 @@ interface TaskCardRow {
   retryCount: number;
   sessionId: string | null;
   dispatchToken: string | null;
+  owner: string | null;
+  heartbeat: number;
   created: number;
   updated: number;
 }
@@ -106,7 +112,7 @@ function rowToCard(row: TaskCardRow): TaskCard {
 }
 
 const CARD_COLUMNS =
-  "id, board_id AS boardId, project_key AS projectKey, number, name, description, ready_status AS readyStatus, exec_status AS execStatus, priority, due, attachments, cwd, use_worktree AS useWorktree, max_retries AS maxRetries, retry_count AS retryCount, session_id AS sessionId, dispatch_token AS dispatchToken, created, updated";
+  "id, board_id AS boardId, project_key AS projectKey, number, name, description, ready_status AS readyStatus, exec_status AS execStatus, priority, due, attachments, cwd, use_worktree AS useWorktree, max_retries AS maxRetries, retry_count AS retryCount, session_id AS sessionId, dispatch_token AS dispatchToken, owner, heartbeat, created, updated";
 
 function getCardRow(id: string): TaskCardRow | undefined {
   return getDb()
@@ -120,6 +126,17 @@ export function getCard(id: string): TaskCard | undefined {
   return row ? rowToCard(row) : undefined;
 }
 
+/** 按 id 列表批量取卡（保持传入顺序；不存在 id 跳过）。可见卡状态查询用，单次 IN 查询。 */
+export function listCardsByIds(ids: string[]): TaskCard[] {
+  if (ids.length === 0) return [];
+  const placeholders = ids.map(() => "?").join(",");
+  const rows = getDb()
+    .prepare(`SELECT ${CARD_COLUMNS} FROM task_cards WHERE id IN (${placeholders})`)
+    .all(...ids) as unknown as TaskCardRow[];
+  const byId = new Map(rows.map((r) => [r.id, rowToCard(r)]));
+  return ids.map((id) => byId.get(id)).filter((c): c is TaskCard => Boolean(c));
+}
+
 /** 某看板的全部任务卡，按编号升序。 */
 export function listCards(boardId: string): TaskCard[] {
   const rows = getDb()
@@ -202,6 +219,8 @@ export function updateCard(
     maxRetries?: number;
     sessionId?: string | null;
     retryCount?: number;
+    owner?: string | null;
+    heartbeat?: number;
   },
 ): TaskCard | null {
   const db = getDb();
@@ -231,6 +250,8 @@ export function updateCard(
   if (patch.maxRetries !== undefined) bump("max_retries", patch.maxRetries);
   if (patch.sessionId !== undefined) bump("session_id", patch.sessionId);
   if (patch.retryCount !== undefined) bump("retry_count", patch.retryCount);
+  if (patch.owner !== undefined) bump("owner", patch.owner);
+  if (patch.heartbeat !== undefined) bump("heartbeat", patch.heartbeat);
   if (sets.length === 0) return rowToCard(existing);
 
   bump("updated", now());
@@ -428,6 +449,21 @@ export function clearDispatchToken(cardId: string, token: string): void {
     .run(cardId, now(), token);
 }
 
+/**
+ * 归属心跳刷新：把本实例拥有且仍在活跃生命周期（running/review/waiting_reply）
+ * 的卡的 heartbeat 推到 now。多实例共库时，非 owner 靠它判断 owner 是否活着
+ * （心跳过期 = owner 已死 → 可接管判定），避免误翻他人正在跑的卡。
+ */
+export function heartbeatOwnedCards(owner: string): number {
+  const res = getDb()
+    .prepare(
+      `UPDATE task_cards SET heartbeat = ?1
+       WHERE owner = ?2 AND exec_status IN ('running', 'review', 'waiting_reply')`,
+    )
+    .run(now(), owner);
+  return Number(res.changes);
+}
+
 /** 调度器已派发且正在运行的任务卡数（全局并发闸门用）。 */
 export function countRunningDispatched(): number {
   const row = getDb()

package/lib/task-scheduler.test.mjs

@@ -0,0 +1,79 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { DatabaseSync } from "node:sqlite";
+import { createJiti } from "jiti";
+
+const jiti = createJiti(import.meta.url, { interopDefault: true, moduleCache: false });
+const { getDb, setDbForTesting } = await jiti.import("./sqlite-db.ts");
+const { createCard, updateCard, getCard, heartbeatOwnedCards } = await jiti.import("./task-card-store.ts");
+const { createBoard } = await jiti.import("./board-store.ts");
+// 只 import 纯函数/归属守卫，不触发 rpc-manager（避免拉起整个 coding-agent SDK）
+const { isCardHandledByInstance, OWNER_STALE_MS } = await jiti.import("./task-scheduler.ts");
+
+function freshDb() {
+  setDbForTesting(new DatabaseSync(":memory:"));
+}
+
+test("迁移后 task_cards 含 owner/heartbeat 列", () => {
+  freshDb();
+  const b = createBoard("proj-a", "看板A");
+  const c = createCard({ boardId: b.id, projectKey: "proj-a", name: "卡" });
+  assert.equal(c.owner, null);
+  assert.equal(c.heartbeat, 0);
+  const cols = getDb().prepare("PRAGMA table_info(task_cards)").all().map((r) => r.name);
+  assert.ok(cols.includes("owner"));
+  assert.ok(cols.includes("heartbeat"));
+});
+
+test("updateCard 可写 owner/heartbeat", () => {
+  freshDb();
+  const b = createBoard("proj-a", "看板A");
+  const c = createCard({ boardId: b.id, projectKey: "proj-a", name: "卡" });
+  const ts = 12345;
+  const updated = updateCard(c.id, { execStatus: "running", owner: "inst-a", heartbeat: ts });
+  assert.equal(updated?.owner, "inst-a");
+  assert.equal(updated?.heartbeat, ts);
+  assert.equal(getCard(c.id)?.owner, "inst-a");
+  assert.equal(getCard(c.id)?.heartbeat, ts);
+});
+
+test("heartbeatOwnedCards 只刷本实例活跃生命周期(running/review/waiting_reply)卡", () => {
+  freshDb();
+  const b = createBoard("proj-a", "看板A");
+  const running = createCard({ boardId: b.id, projectKey: "proj-a", name: "跑" });
+  const review = createCard({ boardId: b.id, projectKey: "proj-a", name: "审" });
+  const waiting = createCard({ boardId: b.id, projectKey: "proj-a", name: "等" });
+  const done = createCard({ boardId: b.id, projectKey: "proj-a", name: "完" });
+  const other = createCard({ boardId: b.id, projectKey: "proj-a", name: "别人" });
+  updateCard(running.id, { execStatus: "running", owner: "me" });
+  updateCard(review.id, { execStatus: "review", owner: "me" });
+  updateCard(waiting.id, { execStatus: "waiting_reply", owner: "me" });
+  updateCard(done.id, { execStatus: "done", owner: "me" });
+  updateCard(other.id, { execStatus: "running", owner: "them" });
+
+  heartbeatOwnedCards("me");
+  assert.ok(getCard(running.id)?.heartbeat > 0);
+  assert.ok(getCard(review.id)?.heartbeat > 0);
+  assert.ok(getCard(waiting.id)?.heartbeat > 0);
+  assert.equal(getCard(done.id)?.heartbeat, 0);      // 结束态不刷新
+  assert.equal(getCard(other.id)?.heartbeat, 0);     // 别人家不刷新
+});
+
+test("isCardHandledByInstance 归属守卫矩阵（#27 核心）", () => {
+  const me = "inst-me";
+  const them = "inst-them";
+  const now = 1_000_000;
+  const fresh = now - 5_000;            // 5s 前心跳（OWNER_STALE_MS=120s 内 → 活着）
+  const stale = now - (OWNER_STALE_MS + 1_000); // 超期 → 已死
+
+  // owner 为空（旧数据）→ 任何实例可处理
+  assert.equal(isCardHandledByInstance({ owner: null, heartbeat: 0 }, me, now), true);
+  // owner == 我 → 我负责
+  assert.equal(isCardHandledByInstance({ owner: me, heartbeat: 0 }, me, now), true);
+  // owner == 他人 且 心跳新鲜 → 跳过（← 防误翻他人正在跑的会话）
+  assert.equal(isCardHandledByInstance({ owner: them, heartbeat: fresh }, me, now), false);
+  // owner == 他人 但 心跳过期 → 接管
+  assert.equal(isCardHandledByInstance({ owner: them, heartbeat: stale }, me, now), true);
+  // 边界：正好 = OWNER_STALE_MS 视为过期（>=）
+  assert.equal(isCardHandledByInstance({ owner: them, heartbeat: now - OWNER_STALE_MS }, me, now), true);
+});

package/lib/task-scheduler.ts

@@ -1,6 +1,7 @@
 import { existsSync } from "fs";
 import { randomUUID } from "crypto";
 import { getBoard } from "./board-store";
+import { reconcileBoard } from "./board-reconcile";
 import { startRpcSession, getRunningRpcSessionIds } from "./rpc-manager";
 import { resolveSessionPath } from "./session-reader";
 import { assignSessionToTask } from "./task-store";
@@ -16,6 +17,7 @@ import {
   updateCard,
   acquireDispatchToken,
   clearDispatchToken,
+  heartbeatOwnedCards,
   type TaskCard,
   type TaskCardQuestion,
 } from "./task-card-store";
@@ -36,6 +38,11 @@ import {
 export const TASK_SCHEDULER_INTERVAL_MS = 10_000;
 export const TASK_SCHEDULER_MAX_CONCURRENCY = 1;
 
+/** 归属心跳刷新周期（独立于长 tick，防审核阻塞期间心跳断更） */
+export const HEARTBEAT_INTERVAL_MS = 10_000;
+/** owner 心跳过期阈值：超时视为 owner 已死，其他实例可接管判定 */
+export const OWNER_STALE_MS = 120_000;
+
 // ============================================================================
 // S3 巡检/审核参数
 // ============================================================================
@@ -58,10 +65,15 @@ export const SESSION_SETTLE_MS = 5_000;
 declare global {
   var __piTaskScheduler: {
     timer: ReturnType<typeof setInterval>;
+    heartbeatTimer: ReturnType<typeof setInterval>;
     startedAt: number;
     /** 最近一次调度动作（挂 globalThis 防 instrumentation 与 API 路由加载两份模块实例不互通） */
     lastAction: TaskSchedulerLastAction;
+    /** 调度器此刻正在做的动作（看板状态展示：工作中/休眠两态）；无=休眠 */
+    activity: SchedulerActivity | null;
   } | undefined;
+  /** 本进程实例 id（防热重载换 id；多实例各持不同 id，作为任务卡 owner） */
+  var __piWebInstanceId: string | undefined;
 }
 
 /** 派发 cwd：card.cwd 优先；否则看板所属项目根（project_key 若是存在的目录）。 */
@@ -111,6 +123,47 @@ async function ensureExecutionSession(
   return { ...fresh, created: true };
 }
 
+/** 本进程实例 id：随机 UUID，globalThis 缓存（热重载不换），多实例各不同。 */
+export function getInstanceId(): string {
+  if (!globalThis.__piWebInstanceId) globalThis.__piWebInstanceId = randomUUID();
+  return globalThis.__piWebInstanceId;
+}
+
+/**
+ * 归属守卫：这张卡的「状态判定」该不该由本实例做（#27 根因修复）。
+ * - owner 为空（旧数据/未升级实例派发）→ 任何实例可处理（保持旧语义）
+ * - owner == 我 → 我负责
+ * - owner == 他人且心跳新鲜 → 他人活着，跳过（防误翻他人正在跑的会话）
+ * - owner == 他人但心跳过期 → 他人已死，接管
+ */
+export function isCardHandledByInstance(
+  card: Pick<TaskCard, "owner" | "heartbeat">,
+  myId: string,
+  now: number,
+): boolean {
+  return !card.owner || card.owner === myId || now - card.heartbeat >= OWNER_STALE_MS;
+}
+
+/**
+ * 自愈：本地 registry 里真实在跑、但卡状态却是 review 的 → 拉回 running 并接管归属。
+ * 兜底任何来源（未升级旧实例 / 竞态 / 手动）把还在跑的卡误标成 review 的情况——
+ * 只有会话确实在跑（isRunning 真）才回拉，真结束待审核的卡不会被动。
+ */
+export async function restoreRunningReviewCards(): Promise<number> {
+  const myId = getInstanceId();
+  const now = Date.now();
+  const runningIds = new Set(getRunningRpcSessionIds());
+  let restored = 0;
+  for (const card of listCardsByExecStatus(["review"])) {
+    if (!card.sessionId) continue;
+    if (!runningIds.has(card.sessionId)) continue;
+    updateCard(card.id, { execStatus: "running", owner: myId, heartbeat: now });
+    console.log(`[task-scheduler] #${card.number} ${card.name} 自愈：会话仍在跑 → 拉回 running`);
+    restored += 1;
+  }
+  return restored;
+}
+
 /** 派发单卡：建/复执行会话 → 命名 #N 标题 → 任务看板归属 → node 绑 session → 发 prompt → running。
  *  跨进程互斥：派发前先原子抢 dispatch_token（谁抢到谁执行），防多实例共库双会话。 */
 export async function dispatchCard(card: TaskCard): Promise<boolean> {
@@ -135,11 +188,16 @@ export async function dispatchCard(card: TaskCard): Promise<boolean> {
     const board = getBoard(card.boardId);
     if (board?.taskId) {
       assignSessionToTask(session.realSessionId, board.taskId);
+      // 注意：不在 assignSessionToTask 后 reconcile——此刻卡 sessionId 未落表，
+      // reconcile 只能补会话卡、建不了 exec 线 → 造成「先出卡后出线」。
+      // 统一在 updateCard(sessionId) 之后触发（补卡+建线同一次事务、一次广播）。
     }
 
     // 会话正忙（已在流式/处理中）：说明上一轮已发过 prompt，直接标 running，不重复发
     if (session.session.isRunning()) {
-      updateCard(card.id, { sessionId: session.realSessionId, execStatus: "running" });
+      updateCard(card.id, { sessionId: session.realSessionId, execStatus: "running", owner: getInstanceId(), heartbeat: Date.now() });
+      // sessionId 落表后立即 reconcile：补执行会话卡 + exec 线（卡线同现，不依赖定时兜底）
+      if (board?.taskId) reconcileTaskBoard(card.boardId);
       watchForAgentEnd(card, session.session);
       clearDispatchToken(card.id, token);
       console.log(`[task-scheduler] #${card.number} ${card.name} 会话忙（复用中），标 running 不重发`);
@@ -148,7 +206,9 @@ export async function dispatchCard(card: TaskCard): Promise<boolean> {
 
     await session.session.send({ type: "prompt", message: buildTaskPrompt(card) });
 
-    updateCard(card.id, { sessionId: session.realSessionId, execStatus: "running" });
+    updateCard(card.id, { sessionId: session.realSessionId, execStatus: "running", owner: getInstanceId(), heartbeat: Date.now() });
+    // sessionId 落表后立即 reconcile：补执行会话卡 + exec 线（卡线同现，不依赖定时兜底）
+    if (board?.taskId) reconcileTaskBoard(card.boardId);
     watchForAgentEnd(card, session.session);
     clearDispatchToken(card.id, token);
     console.log(
@@ -173,6 +233,13 @@ export async function dispatchCard(card: TaskCard): Promise<boolean> {
   }
 }
 
+/** 任务看板派生 reconcile（后端权威）：补执行会话卡 + exec 线，广播到所有客户端 */
+function reconcileTaskBoard(boardId: string): void {
+  void reconcileBoard(boardId).catch((e) =>
+    console.warn(`[task-scheduler] reconcile ${boardId} 异常:`, e?.message ?? e),
+  );
+}
+
 /**
  * 订阅执行会话 agent_end：会话跑完立即把卡转 review（待审核），不等下一轮 reconcile。
  * 事件驱动实现「会话执行完立即进入待审核」。回调只处理卡仍为 running 的情况，避免覆盖后续流转。
@@ -198,9 +265,12 @@ function watchForAgentEnd(card: TaskCard, session: Awaited<ReturnType<typeof sta
 export async function reconcileEndedRunningCards(): Promise<number> {
   const runningIds = new Set(getRunningRpcSessionIds());
   const now = Date.now();
+  const myId = getInstanceId();
   let flipped = 0;
   for (const card of listRunningDispatched()) {
     if (!card.sessionId) continue;
+    // 归属守卫：他人活着拥有的卡不归本实例判定（防误翻别人正在跑的会话，#27 根因）
+    if (!isCardHandledByInstance(card, myId, now)) continue;
     // 会话真实在跑 → 保持 running
     if (runningIds.has(card.sessionId)) continue;
     // 会话不在跑：确认已静默一段时间（防回合间隙误判），才转 review
@@ -216,6 +286,8 @@ export async function reconcileEndedRunningCards(): Promise<number> {
 
 /** 单轮调度：并发闸门未满才派发；最多补满到全局上限。返回本轮派发数。 */
 export async function runSchedulerTick(): Promise<number> {
+  // 自愈：本地在跑但被误标 review 的卡先拉回 running（先于审核，避免对运行中卡审核烧 token）
+  await restoreRunningReviewCards();
   // 先巡检：会话已结束的 running 卡流转走（review），释放闸门（以真实会话状态为准）
   await reconcileEndedRunningCards();
   // S3：回复队列优先 → 审核 review 卡 → 巡检阻塞
@@ -235,7 +307,10 @@ export async function runSchedulerTick(): Promise<number> {
   for (const card of cards) {
     // 并发闸门按 running 数实时判断（上一张派发后 running 可能已满）
     if (countRunningDispatched() >= TASK_SCHEDULER_MAX_CONCURRENCY) break;
-    const ok = await dispatchCard(card);
+    const ok = await withSchedulerActivity(
+      { kind: "dispatch", cardNumber: card.number, cardName: card.name, at: Date.now() },
+      () => dispatchCard(card),
+    );
     if (ok) {
       dispatched += 1;
       setLastAction({ type: "dispatch", cardNumber: card.number, cardName: card.name, at: Date.now() });
@@ -250,12 +325,19 @@ export async function runSchedulerTick(): Promise<number> {
 
 /** 回复队列：answered 且卡仍在 waiting_reply → 发回复续会话 → running。 */
 export async function processReplyQueue(): Promise<number> {
+  const myId = getInstanceId();
+  const now = Date.now();
   let resumed = 0;
   for (const q of listAnswerableQuestions()) {
     const card = getCard(q.cardId);
     if (!card || card.execStatus !== "waiting_reply" || !card.sessionId) continue;
+    // 归属守卫：他人活着拥有的卡不归本实例续会话（防双实例重复发回复）
+    if (!isCardHandledByInstance(card, myId, now)) continue;
     if (countRunningDispatched() >= TASK_SCHEDULER_MAX_CONCURRENCY) break;
-    const ok = await resumeWithAnswer(card, q);
+    const ok = await withSchedulerActivity(
+      { kind: "resume", cardNumber: card.number, cardName: card.name, at: Date.now() },
+      () => resumeWithAnswer(card, q),
+    );
     if (ok) {
       resumed += 1;
       setLastAction({ type: "resume", cardNumber: card.number, cardName: card.name, at: Date.now() });
@@ -273,7 +355,7 @@ async function resumeWithAnswer(card: TaskCard, q: TaskCardQuestion): Promise<bo
       type: "prompt",
       message: `【用户回答了你的提问】\n${q.answer}\n\n请据此继续完成任务。`,
     });
-    updateCard(card.id, { execStatus: "running" });
+    updateCard(card.id, { execStatus: "running", owner: getInstanceId(), heartbeat: Date.now() });
     console.log(`[task-scheduler] 回复续会话 #${card.number} ${card.name}`);
     return true;
   } catch (error) {
@@ -309,8 +391,11 @@ function enterWaitingReply(card: TaskCard, questionHint: string): void {
 /** 审核 review 卡：程序检测失败→failed；否则 AI 审核 → done/failed/waiting_reply/other。 */
 export async function processReviewCards(): Promise<number> {
   const now = Date.now();
+  const myId = getInstanceId();
   let processed = 0;
   for (const card of listCardsByExecStatus(["review"])) {
+    // 归属守卫：他人活着拥有的卡不归本实例审核（防双实例重复审核/判定互覆盖）
+    if (!isCardHandledByInstance(card, myId, now)) continue;
     const snapshot = card.sessionId ? await readSessionAuditSnapshot(card.sessionId) : null;
 
     // 1. 程序检测：最后消息有失败迹象 → 直接 failed（计次重试）
@@ -332,13 +417,16 @@ export async function processReviewCards(): Promise<number> {
     reviewAuditAt.set(card.id, now);
     const cwd = resolveDispatchCwd(card);
     if (!cwd) continue;
-    const result = await runAuditVerdict({
-      cwd,
-      cardNumber: card.number,
-      cardName: card.name,
-      taskDescription: card.description,
-      recentMessages: snapshot.recentText,
-    });
+    const result = await withSchedulerActivity(
+      { kind: "review", cardNumber: card.number, cardName: card.name, at: Date.now() },
+      () => runAuditVerdict({
+        cwd,
+        cardNumber: card.number,
+        cardName: card.name,
+        taskDescription: card.description,
+        recentMessages: snapshot.recentText,
+      }),
+    );
     if (result?.verdict === "done") {
       updateCard(card.id, { execStatus: "done" });
       console.log(`[task-scheduler] #${card.number} 审核通过 → done（${result.reason}）`);
@@ -361,9 +449,12 @@ export async function processReviewCards(): Promise<number> {
 /** running 卡阻塞巡检：最后消息 > BLOCK_IDLE_MS 无进展 → AI 判定阻塞类型 → 处置。 */
 export async function checkRunningCardsBlocked(): Promise<number> {
   const now = Date.now();
+  const myId = getInstanceId();
   let handled = 0;
   for (const card of listCardsByExecStatus(["running"])) {
     if (!card.sessionId) continue;
+    // 归属守卫：他人活着拥有的卡不归本实例巡检
+    if (!isCardHandledByInstance(card, myId, now)) continue;
     // 冷却：同一卡冷却期内不重复判定
     const last = blockCheckAt.get(card.id) ?? 0;
     if (now - last < BLOCK_COOLDOWN_MS) continue;
@@ -374,13 +465,16 @@ export async function checkRunningCardsBlocked(): Promise<number> {
     blockCheckAt.set(card.id, now);
     const cwd = resolveDispatchCwd(card);
     if (!cwd) continue;
-    const result = await runBlockCheck({
-      cwd,
-      cardNumber: card.number,
-      cardName: card.name,
-      taskDescription: card.description,
-      recentMessages: snapshot.recentText,
-    });
+    const result = await withSchedulerActivity(
+      { kind: "blockcheck", cardNumber: card.number, cardName: card.name, at: Date.now() },
+      () => runBlockCheck({
+        cwd,
+        cardNumber: card.number,
+        cardName: card.name,
+        taskDescription: card.description,
+        recentMessages: snapshot.recentText,
+      }),
+    );
     if (!result) continue;
     switch (result.kind) {
       case "sync_server":
@@ -453,7 +547,23 @@ export function startTaskScheduler(): void {
       });
   }, TASK_SCHEDULER_INTERVAL_MS);
   timer.unref?.();
-  const sched = { timer, startedAt: Date.now(), lastAction: { type: "none" as const, at: 0 } };
+  // 归属心跳：独立于长 tick（审核最长 90s），owner 存活期间心跳不断更，
+  // 其他实例据此知道该卡归谁、不误翻。
+  const heartbeatTimer = setInterval(() => {
+    try {
+      heartbeatOwnedCards(getInstanceId());
+    } catch (error) {
+      console.error("[task-scheduler] heartbeat error:", error instanceof Error ? error.message : error);
+    }
+  }, HEARTBEAT_INTERVAL_MS);
+  heartbeatTimer.unref?.();
+  const sched = {
+    timer,
+    heartbeatTimer,
+    startedAt: Date.now(),
+    lastAction: { type: "none" as const, at: 0 },
+    activity: null,
+  };
   globalThis.__piTaskScheduler = sched;
   console.log(`[pi-web] task scheduler started (interval ${TASK_SCHEDULER_INTERVAL_MS}ms, max ${TASK_SCHEDULER_MAX_CONCURRENCY})`);
 }
@@ -477,6 +587,41 @@ export interface TaskSchedulerStatus {
   running: TaskCard[];
   /** 最近一次调度动作 */
   lastAction: TaskSchedulerLastAction;
+  /** 调度器此刻正在做的动作（工作中）；null=休眠 */
+  activity: SchedulerActivity | null;
+  /** 任务卡队列统计（按执行状态实时算，展示用） */
+  queue: TaskSchedulerQueueStats;
+}
+
+/** 调度器当前动作（看板状态展示）。kind：派发/回复续会话/审核/阻塞巡检。 */
+export interface SchedulerActivity {
+  kind: "dispatch" | "resume" | "review" | "blockcheck";
+  cardNumber?: number;
+  cardName?: string;
+  at: number;
+}
+
+export interface TaskSchedulerQueueStats {
+  /** 就绪可派发（todo & 未开始/可重试 & 前置均完成） */
+  dispatchable: TaskCardBrief[];
+  /** 待审核（review 态） */
+  review: TaskCardBrief[];
+  /** 等回复（waiting_reply 态） */
+  waitingReply: TaskCardBrief[];
+  /** 失败（含重试超限） */
+  failed: TaskCardBrief[];
+}
+
+/** 队列卡片轻量字段（展示/定位用，不携带 description 等大字段） */
+export interface TaskCardBrief {
+  id: string;
+  boardId: string;
+  number: number;
+  name: string;
+}
+
+function toBrief(card: TaskCard): TaskCardBrief {
+  return { id: card.id, boardId: card.boardId, number: card.number, name: card.name };
 }
 
 function getLastAction(): TaskSchedulerLastAction {
@@ -486,13 +631,42 @@ function setLastAction(action: TaskSchedulerLastAction): void {
   if (globalThis.__piTaskScheduler) globalThis.__piTaskScheduler.lastAction = action;
 }
 
+/** 读取当前调度器动作（工作中状态），无则 null */
+function getActivity(): SchedulerActivity | null {
+  return globalThis.__piTaskScheduler?.activity ?? null;
+}
+
+/** 置/清当前调度器动作。UI 轮询读到非空 = 该动作工作中。 */
+function setActivity(activity: SchedulerActivity | null): void {
+  if (globalThis.__piTaskScheduler) globalThis.__piTaskScheduler.activity = activity;
+}
+
+/** 包一段调度动作：执行期间置 activity（工作中），结束清空（休眠）。
+ *  串行 tick 内各阶段不嵌套（同 tick 无并发），末尾 clear 不影响其他阶段。 */
+async function withSchedulerActivity<T>(activity: SchedulerActivity, fn: () => Promise<T>): Promise<T> {
+  setActivity(activity);
+  try {
+    return await fn();
+  } finally {
+    setActivity(null);
+  }
+}
+
 /** 当前调度器状态：真实运行中的卡 + 最近动作。UI 轮询展示「正在运行 xxx任务」。
  *  running 只列执行会话真实在跑的卡（以 getRunningRpcSessionIds 为准，不读过期卡状态）。 */
 export function getSchedulerStatus(): TaskSchedulerStatus {
   const runningIds = new Set(getRunningRpcSessionIds());
+  const running = listRunningDispatched().filter((c) => c.sessionId && runningIds.has(c.sessionId));
   return {
     started: Boolean(globalThis.__piTaskScheduler),
-    running: listRunningDispatched().filter((c) => c.sessionId && runningIds.has(c.sessionId)),
+    running,
     lastAction: getLastAction(),
+    activity: getActivity(),
+    queue: {
+      dispatchable: listDispatchableCards().map(toBrief),
+      review: listCardsByExecStatus(["review"]).map(toBrief),
+      waitingReply: listCardsByExecStatus(["waiting_reply"]).map(toBrief),
+      failed: listCardsByExecStatus(["failed"]).map(toBrief),
+    },
   };
 }

package/lib/yjs-room-server.mjs

@@ -0,0 +1,139 @@
+// ============================================================================
+// yjs 协同房间服务器（Hocuspocus 内嵌版）—— 替代 tldraw sync（TLSocketRoom）
+//   - 每看板一个 Y.Doc（documentName = boardId），结构：nodes/edges/view 三个 Y.Map
+//   - 持久化：SQLite（sync.db 独立表 yjs_documents），onStoreDocument 存全量 update
+//   - 内嵌：server.mjs 的 upgrade 事件分流 —— 仅 /connect 走 crossws，其余交 Next
+//   - 服务端权威写：openDirectConnection(boardId).transact() —— 派生 reconcile 用
+//
+// 用法（内嵌）：server.on("upgrade", handleYjsUpgrade) —— 返回 false 表示未处理
+// ============================================================================
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+import { homedir } from "node:os";
+import { join, normalize } from "node:path";
+
+const { DatabaseSync } = require("node:sqlite");
+const { Server } = require("@hocuspocus/server");
+const Y = require("yjs");
+
+// ---- agent dir（与 lib/sqlite-db.ts 同语义）----
+export function getAgentDir() {
+  const envDir = process.env.PI_CODING_AGENT_DIR;
+  if (envDir) {
+    const expanded = envDir.startsWith("~") ? join(homedir(), envDir.slice(1)) : envDir;
+    return normalize(expanded);
+  }
+  return join(homedir(), ".pi", "agent");
+}
+export const YJS_DB_FILE = join(getAgentDir(), "sync.db");
+
+// 单一 DatabaseSync 连接（node:sqlite 同步，单连接线程安全）
+const db = new DatabaseSync(YJS_DB_FILE);
+db.exec(`
+  CREATE TABLE IF NOT EXISTS yjs_documents (
+    board_id TEXT PRIMARY KEY,
+    data     BLOB NOT NULL,
+    updated  INTEGER NOT NULL
+  );
+`);
+
+/** Hocuspocus server 实例（惰性创建） */
+let hocuspocus = null;
+
+/** 建（或复用）Hocuspocus server */
+function getServer() {
+  if (hocuspocus) return hocuspocus;
+  hocuspocus = new Server({
+    // 端口留给外部 httpServer，这里不 listen
+    port: 0,
+    // 客户端断开后延迟持久化再卸载
+    unloadImmediately: false,
+    // 文档变更持久化 debounce（默认 2s，配小一点让写库及时）
+    debounce: 500,
+    async onLoadDocument({ documentName, document }) {
+      const row = db.prepare("SELECT data FROM yjs_documents WHERE board_id = ?").get(documentName);
+      if (row) {
+        try {
+          Y.applyUpdate(document, new Uint8Array(row.data));
+        } catch (e) {
+          console.warn(`[yjs] ${documentName} onLoad 解码失败:`, e?.message ?? e);
+        }
+      }
+    },
+    async onStoreDocument({ documentName, document }) {
+      const update = Y.encodeStateAsUpdate(document);
+      db.prepare(
+        "INSERT INTO yjs_documents (board_id, data, updated) VALUES (?, ?, ?) " +
+          "ON CONFLICT(board_id) DO UPDATE SET data = excluded.data, updated = excluded.updated",
+      ).run(documentName, Buffer.from(update), Date.now());
+    },
+  });
+  return hocuspocus;
+}
+
+/**
+ * 处理一条 WebSocket upgrade 请求（挂在 Node http server 的 "upgrade" 事件）。
+ * 仅 /connect 路径交 Hocuspocus（provider 的 name 参数 = documentName）；
+ * 其余（Next HMR 等）返回 false，调用方转交 Next。
+ * @returns {boolean} 是否已处理
+ */
+export function handleYjsUpgrade(req, socket, head) {
+  let url;
+  try {
+    url = new URL(req.url, "http://localhost");
+  } catch {
+    return false;
+  }
+  if (url.pathname !== "/connect") return false;
+  const server = getServer();
+  server.crossws.handleUpgrade(req, socket, head).catch((e) => {
+    console.error(`[yjs] /connect handleUpgrade 异常:`, e?.message ?? e);
+    try { socket.destroy(); } catch { /* ignore */ }
+  });
+  return true;
+}
+
+/**
+ * 服务端权威写：对指定看板执行一个事务（直接改 Y.Doc，不经 WebSocket）。
+ * transaction(maps, doc) 内用 maps.nodes / maps.edges / maps.view 操作。
+ * 变更自动经 Hocuspocus 广播到已连接客户端并持久化（onStoreDocument）。
+ */
+export async function mutateBoard(boardId, transaction) {
+  const server = getServer();
+  const dc = await server.hocuspocus.openDirectConnection(boardId);
+  try {
+    await dc.transact((document) => {
+      const maps = {
+        nodes: document.getMap("nodes"),
+        edges: document.getMap("edges"),
+        view: document.getMap("view"),
+        ydoc: document,
+      };
+      transaction(maps, document);
+    });
+  } finally {
+    await dc.disconnect().catch(() => {});
+  }
+}
+
+/** 删除看板文档（删除看板时调用） */
+export async function destroyBoardDocument(boardId) {
+  const server = getServer();
+  try {
+    await server.hocuspocus.closeConnections(boardId);
+    db.prepare("DELETE FROM yjs_documents WHERE board_id = ?").run(boardId);
+  } catch (e) {
+    console.warn(`[yjs] destroy ${boardId} 异常:`, e?.message ?? e);
+  }
+}
+
+/** 当前加载中的文档数（诊断用） */
+export function getYjsRoomCount() {
+  return hocuspocus?.hocuspocus?.documents?.size ?? 0;
+}
+
+// ---- 注入 globalThis（供 lib/board-reconcile.ts 调用，避免 Next 打包 node:sqlite）----
+globalThis.__yjsBoard = {
+  mutateBoard,
+  destroyBoardDocument,
+};