feat: M3 — 伏笔账本 + 节奏引擎 + 大纲（含并发记账 bugfix）

- 伏笔账本：纯函数状态机(OPEN/PARTIAL/CLOSED/OVERDUE) + ForeshadowLedger repo；验收后到期扫描(BackgroundTask 自建 session 置 OVERDUE)；登记/状态变更端点
- 节奏 + 三审齐：foreshadow-analyst + pace-checker 并入 LangGraph 并行审(REVIEW_SPECS)，collect 分列落 chapter_reviews(conflicts/foreshadow_sug/pace)，review SSE 加 foreshadow/pace 事件
- 大纲：outliner Agent 产 OutlineResult(含 foreshadow_windows)，POST /outline 逐章 upsert outline 表；GET /foreshadow?status= 看板
- 前端：伏笔四泳道看板(OVERDUE 琥珀) + 大纲编辑器(窗口徽标) + 节奏节拍图(▁▃▅) + 审稿页消费 foreshadow/pace SSE
- bugfix(T3.8)：并行三审共用请求 session 记账触发 'Session is already flushing' → foreshadow/pace 静默丢失；SqlAlchemyLedgerSink.record 改 add-only(靠端点/事务 commit)，加并发回归测试
- M3 E2E：真实 DB + mock 网关零 token 走通 埋设→进展→验收后扫描 OVERDUE→看板 + 大纲含窗口 + 三审齐 SSE/留痕；E2E 暴露并钉住上述 bug
- 门禁绿：mypy 111 / pytest 228(0 xfailed) / alembic 无漂移；前端 gen:api/lint/tsc/vitest 69/build

apps/web/lib/foreshadow/useForeshadow.ts

@@ -0,0 +1,96 @@
+"use client";
+
+import { useCallback, useState } from "react";
+
+import { api } from "@/lib/api/client";
+import { useToast } from "@/components/Toast";
+import type { ForeshadowView } from "@/lib/api/types";
+import {
+  buildRegisterRequest,
+  buildTransitionRequest,
+  extractReason,
+  validationReasonMessage,
+  type ForeshadowStatus,
+  type RegisterInput,
+  type TransitionInput,
+} from "./board";
+
+export interface UseForeshadow {
+  items: ForeshadowView[];
+  busy: boolean;
+  register: (input: RegisterInput) => Promise<boolean>;
+  transition: (code: string, input: TransitionInput) => Promise<boolean>;
+}
+
+// 伏笔登记/状态变更（乐观更新 + 回滚 + Toast）。
+// register：成功后把返回行追加进 items；422 duplicate → 友好提示，不改 items。
+// transition：先乐观替换该行 status，失败回滚到旧 items 并 toast（读 details.reason）。
+export function useForeshadow(initial: ForeshadowView[]): UseForeshadow {
+  const [items, setItems] = useState<ForeshadowView[]>(initial);
+  const [busy, setBusy] = useState(false);
+  const toast = useToast();
+
+  const register = useCallback<UseForeshadow["register"]>(
+    async (input) => {
+      setBusy(true);
+      try {
+        const { data, error } = await api.POST(
+          "/projects/{project_id}/foreshadow",
+          {
+            params: { path: { project_id: input.projectId } },
+            body: buildRegisterRequest(input),
+          },
+        );
+        if (error || !data) {
+          toast(validationReasonMessage(extractReason(error)), "error");
+          return false;
+        }
+        setItems((prev) => [...prev, data]);
+        toast(`已登记伏笔 ${data.code}`, "success");
+        return true;
+      } finally {
+        setBusy(false);
+      }
+    },
+    [toast],
+  );
+
+  const transition = useCallback<UseForeshadow["transition"]>(
+    async (code, input) => {
+      const snapshot = items;
+      // 乐观：本地先改 status（若给了 toStatus）。
+      if (input.toStatus) {
+        const next = input.toStatus as ForeshadowStatus;
+        setItems((prev) =>
+          prev.map((it) => (it.code === code ? { ...it, status: next } : it)),
+        );
+      }
+      setBusy(true);
+      try {
+        const { data, error } = await api.PATCH(
+          "/projects/{project_id}/foreshadow/{code}",
+          {
+            params: {
+              path: { project_id: input.projectId, code },
+            },
+            body: buildTransitionRequest(input),
+          },
+        );
+        if (error || !data) {
+          setItems(snapshot); // 回滚
+          toast(validationReasonMessage(extractReason(error)), "error");
+          return false;
+        }
+        // 用服务端权威行替换（status + progress 都对齐）。
+        setItems((prev) => prev.map((it) => (it.code === code ? data : it)));
+        toast(`已更新 ${data.code}`, "success");
+        return true;
+      } finally {
+        setBusy(false);
+      }
+    },
+    [items, toast],
+  );
+
+  return { items, busy, register, transition };
+}