@baique/pi-web-sky 0.1.35 → 0.1.37

package/lib/audit-session.ts

@@ -0,0 +1,235 @@
+import {
+  createAgentSessionFromServices,
+  createAgentSessionServices,
+  getAgentDir,
+  initTheme,
+  SessionManager,
+  SettingsManager,
+  type SessionMessageEntry,
+} from "@earendil-works/pi-coding-agent";
+import { resolveSessionPath } from "./session-reader";
+
+// ============================================================================
+// 审核/阻塞判定（S3）
+// 用 SessionManager.inMemory()（等价 --no-session）临时会话做一次结构化 AI 判定，
+// 不落盘、不污染执行会话文件；执行会话上下文干净，重试不带审核噪音。
+// ============================================================================
+
+/** review 卡审核判定 */
+export type AuditVerdict = "done" | "failed" | "waiting_reply" | "other";
+/** running 卡阻塞判定 */
+export type BlockKind =
+  | "sync_server"
+  | "infinite_loop"
+  | "rate_limit"
+  | "error"
+  | "asking"
+  | "normal";
+
+export interface AuditInput {
+  cwd: string;
+  cardNumber: number;
+  cardName: string;
+  taskDescription: string;
+  /** 执行会话最后几条 AI 消息文本（供 AI 判定） */
+  recentMessages: string;
+}
+
+export interface AuditVerdictResult {
+  verdict: AuditVerdict;
+  reason: string;
+}
+
+export interface BlockCheckResult {
+  kind: BlockKind;
+  detail: string;
+}
+
+/** 从模型回复里抽取首个 JSON 对象块（容忍思考前缀/前后文）。 */
+function extractJson(text: string): unknown | null {
+  const start = text.indexOf("{");
+  if (start === -1) return null;
+  let depth = 0;
+  for (let i = start; i < text.length; i++) {
+    if (text[i] === "{") depth += 1;
+    else if (text[i] === "}") {
+      depth -= 1;
+      if (depth === 0) {
+        try {
+          return JSON.parse(text.slice(start, i + 1));
+        } catch {
+          return null;
+        }
+      }
+    }
+  }
+  return null;
+}
+
+const AUDIT_TIMEOUT_MS = 90_000;
+
+// ============================================================================
+// 会话快照（程序检测 + 喂给 AI 的最近消息）
+// ============================================================================
+
+export interface SessionAuditSnapshot {
+  /** 程序判定：最后消息有失败迹象（模型报错/工具 isError/exit!=0） */
+  failure: boolean;
+  /** 最后几条 AI 消息文本（喂给 AI 判定） */
+  recentText: string;
+  /** 最后一条消息时间（ms epoch）；0=未知（阻塞检测用） */
+  lastActivityMs: number;
+}
+
+function textOfContent(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .filter((b): b is { type: "text"; text: string } => Boolean(b) && typeof b === "object" && "text" in b)
+      .map((b) => (b as { text: string }).text)
+      .join("\n");
+  }
+  return "";
+}
+
+/** 读执行会话文件：程序判定失败 + 最近消息文本 + 最后活动时间。文件缺失返回 null。 */
+export async function readSessionAuditSnapshot(sessionId: string): Promise<SessionAuditSnapshot | null> {
+  try {
+    const filePath = await resolveSessionPath(sessionId);
+    if (!filePath) return null;
+    const manager = SessionManager.open(filePath);
+    const messages = manager.getEntries().filter((e): e is SessionMessageEntry => e.type === "message");
+    let failure = false;
+    let lastActivityMs = 0;
+    const recent: string[] = [];
+    for (const e of messages.slice(-4)) {
+      const m = e.message;
+      const ts = typeof m.timestamp === "number" ? m.timestamp : new Date(e.timestamp).getTime();
+      if (!Number.isNaN(ts)) lastActivityMs = Math.max(lastActivityMs, ts);
+      if (m.role === "assistant") {
+        if (m.errorMessage) failure = true;
+        const text = textOfContent(m.content);
+        if (text) recent.push(`AI: ${text.slice(0, 400)}`);
+      } else if (m.role === "toolResult") {
+        if (m.isError) failure = true;
+        const details = m.details as { exitCode?: number } | undefined;
+        if (details && typeof details.exitCode === "number" && details.exitCode !== 0) failure = true;
+        const text = textOfContent(m.content);
+        if (text) recent.push(`工具 ${m.toolName}: ${text.slice(0, 300)}`);
+      } else if (m.role === "user") {
+        const text = textOfContent(m.content);
+        if (text) recent.push(`用户: ${text.slice(0, 300)}`);
+      }
+    }
+    return { failure, recentText: recent.join("\n").slice(0, 4000), lastActivityMs };
+  } catch (error) {
+    console.error(
+      `[task-scheduler] 读会话快照失败 ${sessionId}:`,
+      error instanceof Error ? error.message : error,
+    );
+    return null;
+  }
+}
+
+/** 用 inMemory 临时会话跑一次结构化判定。超时/失败返回 null。 */
+async function runStructuredVerdict<T>(
+  cwd: string,
+  instruction: string,
+  input: string,
+): Promise<T | null> {
+  let session: Awaited<ReturnType<typeof createAgentSessionFromServices>>["session"] | null = null;
+  const timer = setTimeout(() => {
+    // 超时兜底：dispose 会中断模型请求
+    if (session && typeof (session as { dispose?: () => void }).dispose === "function") {
+      try { (session as { dispose: () => void }).dispose(); } catch { /* 忽略 */ }
+    }
+  }, AUDIT_TIMEOUT_MS);
+
+  try {
+    initTheme();
+    const agentDir = getAgentDir();
+    const settingsManager = SettingsManager.create(cwd, agentDir);
+    const services = await createAgentSessionServices({
+      cwd,
+      agentDir,
+      settingsManager,
+      resourceLoaderOptions: { extensionFactories: [] },
+    });
+    const manager = SessionManager.inMemory(cwd);
+    const created = await createAgentSessionFromServices({
+      services,
+      sessionManager: manager,
+      noTools: "all",
+    });
+    session = created.session;
+    await session.prompt(`${instruction}\n\n${input}`, {
+      expandPromptTemplates: false,
+      source: "rpc",
+    });
+    await session.waitForIdle();
+    const text = session.getLastAssistantText() ?? "";
+    const parsed = extractJson(text);
+    return (parsed ?? null) as T | null;
+  } catch (error) {
+    console.error(
+      "[audit-session] 判定失败:",
+      error instanceof Error ? error.message : error,
+    );
+    return null;
+  } finally {
+    clearTimeout(timer);
+    if (session) {
+      try { session.dispose(); } catch { /* 忽略 */ }
+    }
+  }
+}
+
+const AUDIT_INSTRUCTION = `你是任务卡审核员。下面给出任务卡信息与执行会话最后几条消息，判断任务执行结果：
+- done: 任务已正确完成
+- failed: 执行失败 / 出错 / 未完成 / 模型报错
+- waiting_reply: AI 正在向用户提问、等待用户输入
+- other: 信息不足，无法判断
+
+只输出一行 JSON（不要输出其他文字）：{"verdict":"done|failed|waiting_reply|other","reason":"简短原因"}`;
+
+/** review 卡审核：返回 done/failed/waiting_reply/other；判定失败返回 null。 */
+export async function runAuditVerdict(input: AuditInput): Promise<AuditVerdictResult | null> {
+  const taskText = [
+    `【任务卡 #${input.cardNumber}】${input.cardName}`,
+    `任务描述：${input.taskDescription || "(空)"}`,
+    ``,
+    `执行会话最后几条消息：`,
+    input.recentMessages || "(无消息)",
+  ].join("\n");
+  const result = await runStructuredVerdict<AuditVerdictResult>(input.cwd, AUDIT_INSTRUCTION, taskText);
+  if (result && ["done", "failed", "waiting_reply", "other"].includes(result.verdict)) {
+    return { verdict: result.verdict, reason: result.reason ?? "" };
+  }
+  return null;
+}
+
+const BLOCK_INSTRUCTION = `你是任务卡巡检员。任务卡执行会话已超过 5 分钟没有进展。根据任务与最后几条消息，判断阻塞类型：
+- sync_server: 正在同步开启服务 / 输出流式日志（长任务，正常）
+- infinite_loop: 死循环 / 重复执行同一操作
+- rate_limit: 模型限流(429) / 节流退避
+- error: 执行报错
+- asking: AI 在提问等待用户输入
+- normal: 正常运行中（长任务）
+
+只输出一行 JSON（不要输出其他文字）：{"kind":"sync_server|infinite_loop|rate_limit|error|asking|normal","detail":"简短说明"}`;
+
+/** running 卡阻塞判定：返回阻塞类型；判定失败返回 null。 */
+export async function runBlockCheck(input: AuditInput): Promise<BlockCheckResult | null> {
+  const taskText = [
+    `【任务卡 #${input.cardNumber}】${input.cardName}`,
+    `任务描述：${input.taskDescription || "(空)"}`,
+    ``,
+    `执行会话最后几条消息：`,
+    input.recentMessages || "(无消息)",
+  ].join("\n");
+  const result = await runStructuredVerdict<BlockCheckResult>(input.cwd, BLOCK_INSTRUCTION, taskText);
+  if (result && ["sync_server", "infinite_loop", "rate_limit", "error", "asking", "normal"].includes(result.kind)) {
+    return { kind: result.kind, detail: result.detail ?? "" };
+  }
+  return null;
+}

package/lib/bash-output.test.mjs

@@ -0,0 +1,63 @@
+import assert from "node:assert/strict";
+import { mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import test from "node:test";
+
+async function loadSubject() {
+  return import("./bash-output.ts");
+}
+
+test("accepts only pi bash logs directly inside the configured temp directory", async () => {
+  const { resolveBashOutputPath } = await loadSubject();
+  const tempRoot = join(tmpdir(), "pi-web-output-tests");
+  const expected = resolve(tempRoot, "pi-bash-ab12.log");
+
+  assert.equal(resolveBashOutputPath(join(tempRoot, "pi-bash-ab12.log"), tempRoot), expected);
+  assert.equal(resolveBashOutputPath(join(tempRoot, "..", "pi-bash-ab12.log"), tempRoot), null);
+  assert.equal(resolveBashOutputPath(join(tempRoot, "pi-bash-ab12.log.bak"), tempRoot), null);
+  assert.equal(resolveBashOutputPath(join(`${tempRoot}-other`, "pi-bash-ab12.log"), tempRoot), null);
+});
+
+test("reads small output and rejects oversized inline output before buffering it", async () => {
+  const { readUtf8FileWithinLimit } = await loadSubject();
+  const dir = await mkdtemp(join(tmpdir(), "pi-web-bash-output-"));
+  const filePath = join(dir, "pi-bash-ab12.log");
+  try {
+    await writeFile(filePath, "shell output", "utf8");
+
+    assert.deepEqual(await readUtf8FileWithinLimit(filePath, 32), {
+      tooLarge: false,
+      content: "shell output",
+      size: 12,
+    });
+    assert.deepEqual(await readUtf8FileWithinLimit(filePath, 4), {
+      tooLarge: true,
+      size: 12,
+    });
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("rejects symbolic links when opening bash output", async (t) => {
+  const { readUtf8FileWithinLimit } = await loadSubject();
+  const dir = await mkdtemp(join(tmpdir(), "pi-web-bash-output-link-"));
+  const targetPath = join(dir, "target.log");
+  const linkPath = join(dir, "pi-bash-link.log");
+  try {
+    await writeFile(targetPath, "not authorized through a link", "utf8");
+    try {
+      await symlink(targetPath, linkPath);
+    } catch (error) {
+      if (error?.code === "EPERM") {
+        t.skip("Creating symbolic links requires additional privileges on this platform");
+        return;
+      }
+      throw error;
+    }
+    await assert.rejects(() => readUtf8FileWithinLimit(linkPath));
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/lib/bash-output.ts

@@ -0,0 +1,53 @@
+import { constants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import { basename, dirname, resolve } from "node:path";
+
+export const MAX_INLINE_BASH_OUTPUT_BYTES = 5 * 1024 * 1024;
+
+export function resolveBashOutputPath(filePath: string, tempRoot: string): string | null {
+  const resolvedPath = resolve(filePath);
+  if (dirname(resolvedPath) !== resolve(tempRoot)) return null;
+  if (!/^pi-bash-[A-Za-z0-9_-]+\.log$/.test(basename(resolvedPath))) return null;
+  return resolvedPath;
+}
+
+export async function openRegularFileNoFollow(filePath: string) {
+  const pathInfo = await lstat(filePath);
+  if (!pathInfo.isFile()) throw new Error("Bash output path is not a regular file");
+
+  const noFollow = typeof constants.O_NOFOLLOW === "number" ? constants.O_NOFOLLOW : 0;
+  const handle = await open(filePath, constants.O_RDONLY | noFollow);
+  try {
+    const fileInfo = await handle.stat();
+    if (!fileInfo.isFile()) throw new Error("Bash output path is not a regular file");
+    return { handle, fileInfo };
+  } catch (error) {
+    await handle.close();
+    throw error;
+  }
+}
+
+export async function readUtf8FileWithinLimit(
+  filePath: string,
+  maxBytes = MAX_INLINE_BASH_OUTPUT_BYTES,
+): Promise<{ tooLarge: true; size: number } | { tooLarge: false; content: string; size: number }> {
+  const { handle, fileInfo } = await openRegularFileNoFollow(filePath);
+  try {
+    if (fileInfo.size > maxBytes) return { tooLarge: true, size: fileInfo.size };
+
+    const buffer = Buffer.alloc(fileInfo.size);
+    let bytesRead = 0;
+    while (bytesRead < buffer.length) {
+      const result = await handle.read(buffer, bytesRead, buffer.length - bytesRead, bytesRead);
+      if (result.bytesRead === 0) break;
+      bytesRead += result.bytesRead;
+    }
+    return {
+      tooLarge: false,
+      content: buffer.subarray(0, bytesRead).toString("utf8"),
+      size: bytesRead,
+    };
+  } finally {
+    await handle.close();
+  }
+}

package/lib/bg-image.ts

@@ -0,0 +1,129 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+
+/**
+ * App wallpaper: original file Blob stored raw in IndexedDB (no re-encode,
+ * no compression), exposed to CSS as `--app-bg-image` on <html>.
+ * Images go through the CSS background layer on `body`; videos are rendered
+ * as an autoplaying muted <video> element by AppShell instead.
+ * Display settings live in lib/wallpaper-settings.ts.
+ */
+
+const DB_NAME = "pi-web";
+const STORE = "bg-image";
+const KEY = "wallpaper";
+
+export type BgKind = "image" | "video" | null;
+
+function openDb(): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const req = indexedDB.open(DB_NAME, 1);
+    req.onupgradeneeded = () => {
+      if (!req.result.objectStoreNames.contains(STORE)) {
+        req.result.createObjectStore(STORE);
+      }
+    };
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+  });
+}
+
+let currentUrl: string | null = null;
+let bgKind: BgKind = null;
+
+function kindOf(blob: Blob | null): BgKind {
+  if (!blob) return null;
+  if (blob.type.startsWith("video/")) return "video";
+  if (blob.type.startsWith("image/")) return "image";
+  return null;
+}
+
+/**
+ * Swap the stored media: revokes the previous object URL, points
+ * `--app-bg-image` at the new one (images only — video uses its own element)
+ * and returns the live object URL.
+ */
+function setBackground(blob: Blob | null): { url: string | null; kind: BgKind } {
+  if (currentUrl) URL.revokeObjectURL(currentUrl);
+  bgKind = kindOf(blob);
+  currentUrl = blob ? URL.createObjectURL(blob) : null;
+  const el = document.documentElement.style;
+  if (bgKind === "image" && currentUrl) {
+    el.setProperty("--app-bg-image", `url("${currentUrl}")`);
+  } else {
+    el.setProperty("--app-bg-image", "none");
+  }
+  return { url: currentUrl, kind: bgKind };
+}
+
+async function loadBackground(): Promise<{
+  loaded: boolean;
+  url: string | null;
+  kind: BgKind;
+}> {
+  try {
+    const db = await openDb();
+    const blob: Blob | null = await new Promise((resolve, reject) => {
+      const req = db.transaction(STORE, "readonly").objectStore(STORE).get(KEY);
+      req.onsuccess = () => resolve((req.result as Blob | undefined) ?? null);
+      req.onerror = () => reject(req.error);
+    });
+    if (!blob) return { loaded: false, ...setBackground(null) };
+    return { loaded: true, ...setBackground(blob) };
+  } catch {
+    // IndexedDB unavailable — background stays off.
+    return { loaded: false, ...setBackground(null) };
+  }
+}
+
+async function writeBackground(blob: Blob | null): Promise<void> {
+  const db = await openDb();
+  await new Promise<void>((resolve, reject) => {
+    const tx = db.transaction(STORE, "readwrite");
+    const store = tx.objectStore(STORE);
+    if (blob) store.put(blob, KEY);
+    else store.delete(KEY);
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+  });
+}
+
+export function useAppBackground() {
+  const [hasBg, setHasBg] = useState(false);
+  const [ready, setReady] = useState(false);
+  const [kind, setKind] = useState<BgKind>(null);
+  const [url, setUrl] = useState<string | null>(null);
+
+  useEffect(() => {
+    let alive = true;
+    loadBackground().then((res) => {
+      if (!alive) return;
+      setHasBg(res.loaded);
+      setUrl(res.url);
+      setKind(res.kind);
+      setReady(true);
+    });
+    return () => {
+      alive = false;
+    };
+  }, []);
+
+  const pick = useCallback(async (file: Blob) => {
+    await writeBackground(file);
+    const res = setBackground(file);
+    setUrl(res.url);
+    setKind(res.kind);
+    setHasBg(true);
+  }, []);
+
+  const remove = useCallback(async () => {
+    await writeBackground(null);
+    setBackground(null);
+    setUrl(null);
+    setKind(null);
+    setHasBg(false);
+  }, []);
+
+  return { hasBg, ready, pick, remove, kind, url };
+}

package/lib/board-events.ts

@@ -0,0 +1,83 @@
+/** 看板工作台 ↔ AppShell 全局事件桥。
+ *
+ * 工作台（SessionWorkbench）内嵌完整 ChatWindow，但卡片在 tldraw 画布内，
+ * 无法直接拿到 AppShell 的 handler/props。两类通道：
+ * 1. 会话内部状态（统计/分支/系统提示）→ ChatWindow 回调直接捕获，卡片内渲染；
+ * 2. 需要 AppShell 参与的动作（打开文件面板/刷新侧栏/浏览器通知）→ 事件桥，
+ *    事件一律携带 sessionId，AppShell 处理时只做对应会话的动作，不退出看板。 */
+/** 工作台内点击消息里的 file: 链接 → AppShell 打开右侧文件面板 */
+export const BOARD_OPEN_FILE_EVENT = "pi-web:board-open-file";
+
+/** 工作台内 fork 出新会话 → AppShell 刷新侧栏（不切换当前会话/退出看板） */
+export const BOARD_SESSION_FORKED_EVENT = "pi-web:board-session-forked";
+
+/** 看板内新建会话（新会话卡转正）→ AppShell 刷新侧栏，新会话出现在左侧树 */
+export const BOARD_SESSION_CREATED_EVENT = "pi-web:board-session-created";
+
+/** 看板内删除会话（画布删卡）→ AppShell 刷新侧栏（左侧树移除该会话） */
+export const BOARD_SESSION_DELETED_EVENT = "pi-web:board-session-deleted";
+
+/** 看板内会话改名 → AppShell 刷新侧栏（左侧树名称同步） */
+export const BOARD_SESSION_RENAMED_EVENT = "pi-web:board-session-renamed";
+
+/** 工作台内会话运行结束 → AppShell 刷新侧栏 + 浏览器通知 */
+export const BOARD_AGENT_END_EVENT = "pi-web:board-agent-end";
+
+/** 工作台内扩展发起阻塞请求 → AppShell 浏览器通知 */
+export const BOARD_ATTENTION_NEEDED_EVENT = "pi-web:board-attention-needed";
+
+/** 看板画布结构变化（清空/清理失效）→ BoardSection 刷新节点计数 */
+export const BOARD_CANVAS_CHANGED_EVENT = "pi-web:board-canvas-changed";
+
+/** 任务卡 API 操作 bump 了 boards.updated → useBoardCanvas 刷新乐观锁基线 */
+export const BOARD_BASE_UPDATED_EVENT = "pi-web:board-base-updated";
+
+declare global {
+  interface WindowEventMap {
+    "pi-web:board-open-file": CustomEvent<{ sessionId: string; filePath: string }>;
+    "pi-web:board-session-forked": CustomEvent<{ sessionId: string; newSessionId: string }>;
+    "pi-web:board-session-created": CustomEvent<{ sessionId: string; nodeId?: string }>;
+    "pi-web:board-session-deleted": CustomEvent<{ sessionId: string }>;
+    "pi-web:board-session-renamed": CustomEvent<{ sessionId: string; name?: string }>;
+    "pi-web:board-agent-end": CustomEvent<{ sessionId: string; sessionName?: string }>;
+    "pi-web:board-attention-needed": CustomEvent<{ sessionId: string; title?: string; method: string }>;
+    "pi-web:board-canvas-changed": CustomEvent<{ boardId: string }>;
+    "pi-web:board-base-updated": CustomEvent<{ boardId: string; updated: number }>;
+  }
+}
+
+export function dispatchBoardOpenFile(sessionId: string, filePath: string): void {
+  window.dispatchEvent(new CustomEvent(BOARD_OPEN_FILE_EVENT, { detail: { sessionId, filePath } }));
+}
+
+export function dispatchBoardSessionForked(sessionId: string, newSessionId: string): void {
+  window.dispatchEvent(new CustomEvent(BOARD_SESSION_FORKED_EVENT, { detail: { sessionId, newSessionId } }));
+}
+
+export function dispatchBoardSessionCreated(sessionId: string, nodeId?: string): void {
+  window.dispatchEvent(new CustomEvent(BOARD_SESSION_CREATED_EVENT, { detail: { sessionId, nodeId } }));
+}
+
+export function dispatchBoardSessionDeleted(sessionId: string): void {
+  window.dispatchEvent(new CustomEvent(BOARD_SESSION_DELETED_EVENT, { detail: { sessionId } }));
+}
+
+export function dispatchBoardSessionRenamed(sessionId: string, name?: string): void {
+  window.dispatchEvent(new CustomEvent(BOARD_SESSION_RENAMED_EVENT, { detail: { sessionId, name } }));
+}
+
+export function dispatchBoardAgentEnd(sessionId: string, sessionName?: string): void {
+  window.dispatchEvent(new CustomEvent(BOARD_AGENT_END_EVENT, { detail: { sessionId, sessionName } }));
+}
+
+export function dispatchBoardAttentionNeeded(sessionId: string, request: { title?: string; method: string }): void {
+  window.dispatchEvent(new CustomEvent(BOARD_ATTENTION_NEEDED_EVENT, { detail: { sessionId, ...request } }));
+}
+
+export function dispatchBoardCanvasChanged(boardId: string): void {
+  window.dispatchEvent(new CustomEvent(BOARD_CANVAS_CHANGED_EVENT, { detail: { boardId } }));
+}
+
+export function dispatchBoardBaseUpdated(boardId: string, updated: number): void {
+  window.dispatchEvent(new CustomEvent(BOARD_BASE_UPDATED_EVENT, { detail: { boardId, updated } }));
+}

package/lib/board-purge.test.mjs

@@ -0,0 +1,66 @@
+import { test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { DatabaseSync } from "node:sqlite";
+import { randomUUID } from "node:crypto";
+import { createJiti } from "jiti";
+
+const jiti = createJiti(import.meta.url, { interopDefault: true, moduleCache: false });
+const { setDbForTesting } = await jiti.import("./sqlite-db.ts");
+const { createBoard, addNode, getBoardCanvas } = await jiti.import("./board-store.ts");
+const { purgeOrphanBoardCards } = await jiti.import("./board-purge.ts");
+
+const PROJECT = "test-project";
+let db;
+
+beforeEach(() => {
+  db = new DatabaseSync(":memory:");
+  setDbForTesting(db);
+});
+
+afterEach(() => {
+  db.close();
+});
+
+test("purgeOrphanBoardCards: 删孤儿卡片（会话不存在）+ 保留 draft 卡 + 幂等", async () => {
+  const b = createBoard(PROJECT, "b");
+  // 孤儿卡：refId 指向不存在的会话（随机 UUID，文件系统必无）
+  const orphanId = randomUUID();
+  const orphan = addNode(b.id, { x: 0, y: 0, refId: orphanId });
+  assert.ok(orphan);
+  // draft 卡：refId 为空，不删
+  const draft = addNode(b.id, { x: 100, y: 0, refId: null });
+  assert.ok(draft);
+
+  const r = await purgeOrphanBoardCards();
+  assert.equal(r.deletedNodes, 1);
+  assert.deepEqual(r.boards, [b.id]);
+
+  const canvas = getBoardCanvas(b.id);
+  assert.equal(canvas?.nodes.length, 1);
+  assert.equal(canvas?.nodes[0].id, draft.id); // draft 保留
+
+  // 幂等：再次清理全 0
+  const r2 = await purgeOrphanBoardCards();
+  assert.equal(r2.deletedNodes, 0);
+  assert.equal(r2.deletedEdges, 0);
+  assert.deepEqual(r2.boards, []);
+});
+
+test("purgeOrphanBoardCards: 级联删连线", async () => {
+  const b = createBoard(PROJECT, "b");
+  const orphanId = randomUUID();
+  const orphan = addNode(b.id, { x: 0, y: 0, refId: orphanId });
+  const keep = addNode(b.id, { x: 100, y: 0, refId: null }); // draft 卡（不删）
+  const { addEdge } = await jiti.import("./board-store.ts");
+  assert.ok(orphan && keep);
+  // 孤儿卡 ←→ draft 卡的连线
+  assert.ok(addEdge(b.id, { fromId: orphan.id, toId: keep.id, label: "x" }));
+
+  const r = await purgeOrphanBoardCards();
+  assert.equal(r.deletedNodes, 1);
+  assert.equal(r.deletedEdges, 1); // 指向孤儿卡的边被级联删
+  const canvas = getBoardCanvas(b.id);
+  assert.equal(canvas?.nodes.length, 1);
+  assert.equal(canvas?.nodes[0].id, keep.id); // draft 保留
+  assert.equal(canvas?.edges.length, 0); // 连线已清
+});