add-coder 0.3.39 → 0.3.40

package/templates/core/scripts/mcp-server/tools/hitl.ts

@@ -23,7 +23,7 @@ import {
   buildHitlProposalMarkdown,
   applyHitlDecisionToProposal,
 } from "../shared/hitl-proposal-content.js"
-import { HITL_APPROVAL_WIDGET_URI } from "../shared/hitl-ui.js"
+import { getHitlApprovalWidgetUri } from "../shared/hitl-ui.js"
 
 // 无类型边界单点（zod 托管）：动态加载的 prisma client 在此一次性转为运行期校验的泛型委托
 const db = {
@@ -49,6 +49,8 @@ function elicitFormSchema(
 
 export function registerHitlTools(server: ToolRegistrar) {
   const runtimeContext = getRuntimeContext()
+  // [2026-09-21 修复] widget 资源 URI = 基名 + HTML 内容哈希（宿主把 URI 当缓存键 ⇒ 改 HTML 自动失效）
+  const WIDGET_URI = getHitlApprovalWidgetUri()
 
   // ═══════════════ 辅助：按安装环境裁决交互模式（caijuehub: hitl-interaction-rules.toml） ═══════════════
   const _interaction = (() => {
@@ -186,8 +188,8 @@ export function registerHitlTools(server: ToolRegistrar) {
     }),
     annotations: { readOnlyHint: true },
     _meta: {
-      ui: { resourceUri: HITL_APPROVAL_WIDGET_URI },
-      "openai/outputTemplate": HITL_APPROVAL_WIDGET_URI,
+      ui: { resourceUri: WIDGET_URI },
+      "openai/outputTemplate": WIDGET_URI,
       "openai/toolInvocation/invoking": "正在加载 HITL 审批表…",
       "openai/toolInvocation/invoked": "HITL 审批表已加载",
     },
@@ -246,14 +248,22 @@ export function registerHitlTools(server: ToolRegistrar) {
         dimensions,
         stale,
         // 服务端无法得知客户端是否真的渲染了 widget —— 如实标注 unknown，不谎报
-        ui: { resourceUri: HITL_APPROVAL_WIDGET_URI, rendered: "unknown" as const },
+        // requiresHostFlag：宿主侧开关（Codex /experimental → enable_mcp_apps）；未开启时 widget 必然加载失败
+        ui: {
+          resourceUri: WIDGET_URI,
+          rendered: "unknown" as const,
+          requiresHostFlag: "experimental.enable_mcp_apps",
+        },
         fallback: { markdownPath, htmlPath },
       }
       const fallbackHint = markdownPath || htmlPath
+      // [2026-09-21 修复] 把「为什么 widget 不显示」的两个确定原因写进返回文本：
+      //   ① 宿主开关未开（Codex /experimental → enable_mcp_apps）；② 工具元数据变更后未重连 MCP server。
+      const widgetHint = `widget 若未显示：「This app couldn't be loaded」⇒ ① 确认宿主已开启 /experimental → enable_mcp_apps（Codex）；② 重启/重连 MCP server（工具元数据与资源 URI 变更后必须重连）。降级入口：${fallbackHint}`
       const text =
         stale.stale === true
-          ? `已加载 ${planName} round ${current.round} 的 ${dimensions.length} 个审批维度。⚠️ 当前 server 进程早于产物更新（需重启）；widget 若未显示，降级入口：${fallbackHint}`
-          : `已加载 ${planName} round ${current.round} 的 ${dimensions.length} 个审批维度。widget 若未显示，降级入口：${fallbackHint}`
+          ? `已加载 ${planName} round ${current.round} 的 ${dimensions.length} 个审批维度。⚠️ 当前 server 进程早于产物更新（需重启）；${widgetHint}`
+          : `已加载 ${planName} round ${current.round} 的 ${dimensions.length} 个审批维度。${widgetHint}`
       return {
         content: [{ type: "text" as const, text }],
         structuredContent: output,
@@ -266,8 +276,8 @@ export function registerHitlTools(server: ToolRegistrar) {
          * + 资源 mimeType 为 `text/html;profile=mcp-app` + 资源存在 + dimensions 非空。
          */
         _meta: {
-          ui: { resourceUri: HITL_APPROVAL_WIDGET_URI },
-          "openai/outputTemplate": HITL_APPROVAL_WIDGET_URI,
+          ui: { resourceUri: WIDGET_URI },
+          "openai/outputTemplate": WIDGET_URI,
         },
       }
     } catch (e) {

package/templates/core/scripts/mcp-server/tools/index.ts

@@ -8,9 +8,11 @@ import { registerGatewayTools } from "./gateway/index.js"
 import { registerHookEventTools } from "./hook-event-report.js"
 import { registerHitlTools } from "./hitl.js"
 import { registerPlanTools } from "./plan.js"
+import { registerPlanLifecycleTools } from "./plan-lifecycle.js"
 import { registerReviewTools } from "./review.js"
 import { registerMemoryTools } from "./memory.js"
 import { registerMemoryCompatTools } from "./memory-compat.js"
+import { registerWidgetProbeTools } from "./widget-probe.js"
 import { PROJECT_ID } from "../shared/env.js"
 import type { ToolRegistrar } from "./registrar.js"
 
@@ -23,6 +25,7 @@ const READ_TOOLS = new Set([
   "get_project_context", "find_related_docs", "get_db_schema", "query_audit_logs",
   "plan_status", "review_status", "status_hitl", "contract_status",
   "render_hitl_approval",
+  "probe_widget_render",
   "check_dps", "check_rahs", "check_add_route_status", "check_spec_sync",
   "check_add_route_completeness", "check_phase_symmetry", "check_failure_path",
   "check_add_compliance", "get_hook_events",
@@ -107,8 +110,10 @@ export function registerAllTools(server: McpServer) {
   registerHookEventTools(registrar)  // 1 tool: get_hook_events
   registerHitlTools(registrar)       // 4 tools: create_hitl / update_hitl / status_hitl / render_hitl_approval
   registerPlanTools(registrar)       // 3 tools: plan_track / plan_status / plan_sync
+  registerPlanLifecycleTools(registrar) // 1 tool: plan_update（关闭/重开唯一入口；round 与 reopenCycle 语义分离）
   registerReviewTools(registrar)     // 3 tools: review_track / review_status / review_sync
-  registerMemoryTools(registrar)     // 8 tools: propose_memory / recall_memory / get_memory / list_memories / review_memory / resolve_memory / feedback_memory / get_memory_health
+  registerMemoryTools(registrar)     // 9 tools: propose_memory / recall_memory / get_memory / list_memories / review_memory / resolve_memory / feedback_memory / get_memory_health / refresh_memory_snapshots
   registerMemoryCompatTools(registrar) // 6 tools: 5 个 v1 弃用门面（append_memory/search_memory/read_memory/link_memory/memory_stats）+ forget_memory（合规清除）
-  // Total: 44 tools
+  registerWidgetProbeTools(registrar)  // 1 tool: probe_widget_render（面板渲染诊断，只读）
+  // Total: 46 tools
 }

package/templates/core/scripts/mcp-server/tools/memory.ts

@@ -1,9 +1,10 @@
 /*
  * Memory 治理面 MCP 工具（Spec §8，Plan §6.1/§6.2）
  *
- * 8 个 MVP 工具：
+ * 9 个工具：
  *   propose_memory / recall_memory / get_memory / list_memories
  *   review_memory / resolve_memory / feedback_memory / get_memory_health
+ *   refresh_memory_snapshots（2026-09-21 接线：下游唯一可调用的 L1/L2 快照入口）
  *
  * 横切契约：
  * - 所有写工具与读工具均强制 repositoryRef === runtimeContext.projectKey（ERR_REPOSITORY_MISMATCH）
@@ -12,8 +13,12 @@
  * - 状态迁移走领域状态机 assertTransition + AuditLog 打点（ADD-5）
  */
 import * as z from "zod/v4"
+import { existsSync, readFileSync, statSync } from "node:fs"
+import { join } from "node:path"
 import type { ToolRegistrar } from "./registrar.js"
 import { textResponse, errorResponse } from "../shared/response.js"
+import { expandForIndexWithMethod, jiebaUnavailableReason, segmentForMatch } from "../shared/memory/retrieval/cjk-segmenter.js"
+import { checkFtsFingerprint } from "../shared/memory/retrieval/fts-fingerprint.js"
 import { prisma } from "../shared/prisma.js"
 import { DATABASE_URL, getRuntimeContext } from "../shared/env.js"
 import {
@@ -52,6 +57,18 @@ import {
 } from "../shared/memory/embedding/index.js"
 import { createPgVectorAdapter } from "../shared/memory/retrieval/vector/pgvector.js"
 import { createSqliteVecAdapter } from "../shared/memory/retrieval/vector/sqlite-vec.js"
+import {
+  refreshL1Snapshot,
+  refreshL2Snapshot,
+  type SnapshotDeps,
+} from "../shared/memory/jobs/snapshot.js"
+import { drainEvidenceQueue } from "../shared/memory/jobs/evidence-collector.js"
+import {
+  recallMode,
+  MEMORY_DIR_NAME,
+  L1_SNAPSHOT_FILE,
+  L1_SNAPSHOT_TTL_MS,
+} from "../shared/memory/switches.js"
 
 /** 测试可注入依赖（生产默认从 prisma/DATABASE_URL 构建） */
 export interface MemoryToolDeps {
@@ -66,6 +83,19 @@ const SCOPE_TYPES = ["ORGANIZATION", "REPOSITORY", "BRANCH", "MODULE", "PATH", "
 const RECALL_OUTCOMES = ["UNKNOWN", "USED", "USEFUL", "IRRELEVANT", "OUTDATED", "CONTRADICTED", "HARMFUL"] as const
 
 export function registerMemoryTools(server: ToolRegistrar, deps: MemoryToolDeps = {}) {
+  /**
+   * 写入期检索展开（Plan Task 2.4 / Spec §3 R4）。
+   * 与查询侧共用 `segmentForMatch`（jieba 主 / bigram 兜底）⇒ 读写同源。
+   * **展开为空而原文非空 ⇒ 抛错**（调用方转成写入失败）：宁可写不进去，也不能写出"存了但检索不到"的行。
+   */
+  const requireSearchText = (topic: string, content: string): string => {
+    const { text, method } = expandForIndexWithMethod(`${topic} ${content}`)
+    if (!text && `${topic}${content}`.trim().length > 0) {
+      throw new Error(`检索展开失败：topic/content 非空但 token 为空（分词器=${method}），拒绝写入以免产生不可检索行`)
+    }
+    return text
+  }
+
   const runtimeContext = getRuntimeContext()
 
   // 无类型边界单点（zod 托管）：动态 client → 运行期校验的泛型委托
@@ -233,6 +263,9 @@ export function registerMemoryTools(server: ToolRegistrar, deps: MemoryToolDeps
       const created = await memoryDb.create({
         data: {
           kind, topic, content,
+          // 检索展开（Plan Task 2.4）：写入期产出，与查询侧共用同一 tokenization 契约；
+          // 展开为空而原文非空 ⇒ 拒绝写入（禁止产生"存进去但检索不到"的行，不静默）
+          searchText: requireSearchText(topic, content),
           summary: (args.summary as string | undefined) ?? null,
           scopeType, scopeValue, repositoryRef,
           importance: (args.importance as number | undefined) ?? 0.5,
@@ -642,13 +675,214 @@ export function registerMemoryTools(server: ToolRegistrar, deps: MemoryToolDeps
         ...lexical.map((l) => l.health()),
       ])
 
+      // ── 接线自检（2026-09-21 Plan Task 3.1）：回答"记忆到底接没接上" ──
+      // 只报告不修改：不写用户 env、不改开关，只给可执行的修复指引。
+      const memoryDir = join(runtimeContext.projectRoot, runtimeContext.magicDir, MEMORY_DIR_NAME)
+      const l1Path = join(memoryDir, L1_SNAPSHOT_FILE)
+      const wiringWarnings: Array<{ code: string; detail: string; fixHint: string }> = []
+      const mode = recallMode()
+
+      if (!existsSync(memoryDir)) {
+        wiringWarnings.push({
+          code: "MEMORY_DIR_MISSING",
+          detail: `${runtimeContext.magicDir}/${MEMORY_DIR_NAME}/ 不存在（快照与采证队列均未接线）`,
+          fixHint: "运行 `npx add-coder sync`（安装期会自动生成），或调用 refresh_memory_snapshots",
+        })
+      }
+      if (mode === "shadow") {
+        const recent = await recallDb.findMany({
+          where: { repositoryRef, createdAt: { gte: new Date(Date.now() - 30 * 86400000) } },
+          take: 1,
+        })
+        if (recent.length === 0) {
+          wiringWarnings.push({
+            code: "SHADOW_ZERO_RECALL",
+            detail: "当前档位 shadow 且近 30 天零召回：记忆从未进入会话",
+            fixHint: "去掉 ADD_MEMORY_RECALL_MODE 或设为 inject（默认），或直接调用 recall_memory 显式召回",
+          })
+        }
+      }
+      if (existsSync(l1Path)) {
+        const ageMs = Date.now() - statSync(l1Path).mtimeMs
+        if (ageMs > L1_SNAPSHOT_TTL_MS) {
+          wiringWarnings.push({
+            code: "SNAPSHOT_STALE",
+            detail: `L1 快照已过期（${Math.floor(ageMs / 86400000)} 天 > TTL 7 天）：注入会被跳过`,
+            fixHint: "调用 refresh_memory_snapshots，或运行 {magicDir}/scripts/memory/memory-jobs.ts refresh-l1",
+          })
+        }
+        const content = readFileSync(l1Path, "utf-8")
+        if (/本仓库暂无已治理记忆|本次查询未命中已治理记忆/.test(content)) {
+          wiringWarnings.push({
+            code: "SNAPSHOT_EMPTY",
+            detail: "L1 快照已接线但 0 条（ACTIVE=0 或过滤过严）：会话启动不会拿到任何记忆",
+            fixHint: "先用 propose_memory 沉淀，再经 review_memory → resolve_memory 升为 ACTIVE",
+          })
+        }
+      } else if (existsSync(memoryDir)) {
+        wiringWarnings.push({
+          code: "SNAPSHOT_MISSING",
+          detail: `L1 快照缺失: ${runtimeContext.magicDir}/${MEMORY_DIR_NAME}/${L1_SNAPSHOT_FILE}`,
+          fixHint: "调用 refresh_memory_snapshots（或运行 memory-jobs.ts refresh-l1 / npx add-coder sync）",
+        })
+      }
+
+      // 词法口径（轮 3 / Task 3.7）：主通道用哪套 tokenization + 指纹是否需要重索引。
+      // 为什么必须在健康检查里：`searchText` 是写入期产出的 token 串，分词器/词典一变历史行就"索引在、命中不了"，
+      // 且不报错 ⇒ 只能靠这里显式透出，否则降级是静默的。
+      const probe = segmentForMatch("端口契约")
+      const fingerprint = checkFtsFingerprint(runtimeContext.projectRoot, runtimeContext.magicDir)
+      const lexicalProfile = {
+        /** 当前实际生效的分词器：jieba = 主通道；bigram = 兜底（降级） */
+        method: probe.method,
+        /** jieba 不可用/切分异常的原因（method=bigram 时必非空；禁止静默降级） */
+        degradedReason: jiebaUnavailableReason(),
+        userDict: probe.userDict ?? false,
+        fingerprint: {
+          current: fingerprint.current.value,
+          recorded: fingerprint.recorded?.fingerprint ?? null,
+          requiresReindex: fingerprint.requiresReindex,
+          reason: fingerprint.reason,
+        },
+      }
+      if (lexicalProfile.method === "bigram") {
+        wiringWarnings.push({
+          code: "LEXICAL_BIGRAM_FALLBACK",
+          detail: `分词主通道降级为 bigram（${lexicalProfile.degradedReason ?? "原因未知"}）：词级判别力下降，长尾召回会变差`,
+          fixHint: "安装 @node-rs/jieba（optionalDependency）或检查平台二进制是否可用；生效后 memory:reindex --apply 重算 searchText",
+        })
+      }
+      if (lexicalProfile.fingerprint.requiresReindex) {
+        wiringWarnings.push({
+          code: "LEXICAL_FINGERPRINT_STALE",
+          detail: `检索指纹需重索引：${lexicalProfile.fingerprint.reason}`,
+          fixHint: "运行 add-coder memory:reindex --probe 查看明细 → --apply 重建 → 回填脚本重算 searchText",
+        })
+      }
+
       return textResponse(JSON.stringify({
         repositoryRef,
         backlog: { candidate: backlog.CANDIDATE ?? 0, pending: backlog.PENDING ?? 0, byStatus: backlog },
         leakage: { checkedRecalls: recentRecalls.length, crossRepositorySelections: leakage },
         providers: { embedding: embeddingHealth },
         index: ftsHealth ?? { component: "fts", status: "unavailable", detail: "无 lexical adapter" },
+        // 词法口径（新增字段）：主通道分词器 / 降级原因 / 指纹是否需重索引
+        lexicalProfile,
+        // 接线状态（新增字段，既有字段保持不变）：ok = 四项告警全空
+        wiring: {
+          status: wiringWarnings.length === 0 ? "ok" : "warning",
+          recallMode: mode,
+          snapshotPath: l1Path,
+          warnings: wiringWarnings,
+        },
       }))
     } catch (e) { return fail(e) }
   })
+
+  // ===== 9. refresh_memory_snapshots（2026-09-21 接线：下游唯一可调用的快照入口） =====
+  server.registerTool("refresh_memory_snapshots", {
+    description: "刷新记忆快照并消费采证队列：drain evidence-queue → refresh L1（默认）/ L2（需 query）。这是下游唯一可调用的快照入口（init / sync / memory-jobs CLI 复用同一实现）。原子写、幂等、token 预算取 ADD_MEMORY_MAX_TOKENS（默认 600）；任一子步失败都会逐条列出（failed=true），不静默吞错。",
+    inputSchema: z.object({
+      repositoryRef: z.string().describe("仓库标识（必须等于运行时 projectKey）"),
+      levels: z.enum(["l1", "l2", "both"]).optional().default("l1").describe("刷新层级：默认 l1"),
+      query: z.string().optional().describe("levels 含 l2 时必填：L2 快照的召回意图"),
+      drainEvidence: z.boolean().optional().default(true).describe("是否先消费 evidence-queue（默认是）"),
+    }),
+  }, async (args: Record<string, unknown>, _ctx: unknown) => {
+    try {
+      const repositoryRef = args.repositoryRef as string
+      assertRepository(repositoryRef)
+      const levels = (args.levels as "l1" | "l2" | "both" | undefined) ?? "l1"
+      const query = args.query as string | undefined
+      const drain = (args.drainEvidence as boolean | undefined) ?? true
+      if (levels !== "l1" && !query) {
+        return errorResponse("levels 含 l2 时必须提供 query（L2 是按 query 的上下文快照），不接受静默降级为 L1")
+      }
+
+      const snapshotDeps: SnapshotDeps = {
+        repositoryRef,
+        projectDir: runtimeContext.projectRoot,
+        magicDir: runtimeContext.magicDir,
+        lexical,
+        fetchByIds: async (ids) =>
+          await memoryDb.findMany({
+            where: { id: { in: ids } },
+            include: { supersedes: { select: { id: true } } },
+          }),
+        fetchEvidenceSourceRefs: async (memoryIds) => {
+          const links = await linkDb.findMany({ where: { memoryId: { in: memoryIds } } })
+          const evIds = [...new Set(links.map((l) => l.evidenceId))]
+          const evs = evIds.length > 0 ? await evidenceDb.findMany({ where: { id: { in: evIds } } }) : []
+          const refById = new Map(evs.map((e) => [e.id, e.sourceRef]))
+          const out = new Map<string, string[]>()
+          for (const l of links) {
+            const ref = refById.get(l.evidenceId)
+            if (!ref) continue
+            const arr = out.get(l.memoryId) ?? []
+            arr.push(ref)
+            out.set(l.memoryId, arr)
+          }
+          return out
+        },
+        audit: {
+          createRecall: (data) => recallDb.create({ data: data }),
+          createRecallItem: (data) => recallItemDb.create({ data: data }),
+        },
+      }
+
+      const steps: Array<{ name: string; ok: boolean; detail: string }> = []
+
+      if (drain) {
+        try {
+          const r = await drainEvidenceQueue({
+            projectDir: runtimeContext.projectRoot,
+            magicDir: runtimeContext.magicDir,
+            repositoryRef,
+            evidenceDb,
+          })
+          // 行级失败不吞：坏行计入 errors 并原样透出（fail-open 到行，但绝不静默）
+          steps.push({
+            name: "drain-evidence",
+            ok: r.errors.length === 0,
+            detail: r.errors.length === 0
+              ? `消费 ${r.processed} 条（跳过 ${r.skipped}），offset=${r.newOffset}`
+              : `消费 ${r.processed} 条，${r.errors.length} 行失败：${r.errors.slice(0, 3).join("; ")}`,
+          })
+        } catch (e) {
+          steps.push({ name: "drain-evidence", ok: false, detail: e instanceof Error ? e.message : String(e) })
+        }
+      }
+
+      const files: Array<{ level: "L1" | "L2"; path: string; itemCount: number; injectedTokens: number }> = []
+
+      if (levels === "l1" || levels === "both") {
+        try {
+          const r = await refreshL1Snapshot(snapshotDeps)
+          files.push({ level: "L1", path: r.path, itemCount: r.itemCount, injectedTokens: r.injectedTokens })
+          steps.push({ name: "refresh-l1", ok: true, detail: `${r.itemCount} 条 / ${r.injectedTokens} tokens → ${r.path}` })
+        } catch (e) {
+          steps.push({ name: "refresh-l1", ok: false, detail: e instanceof Error ? e.message : String(e) })
+        }
+      }
+
+      if (levels === "l2" || levels === "both") {
+        try {
+          const r = await refreshL2Snapshot(snapshotDeps, query as string, "refresh-l2")
+          files.push({ level: "L2", path: r.path, itemCount: r.itemCount, injectedTokens: r.injectedTokens })
+          steps.push({ name: "refresh-l2", ok: true, detail: `${r.itemCount} 条 / ${r.injectedTokens} tokens → ${r.path}` })
+        } catch (e) {
+          steps.push({ name: "refresh-l2", ok: false, detail: e instanceof Error ? e.message : String(e) })
+        }
+      }
+
+      const failed = steps.some((s) => !s.ok)
+      const payload = { repositoryRef, mode: recallMode(), steps, files, failed }
+      const body = JSON.stringify(payload)
+      return textResponse(
+        failed
+          ? `⚠️ 快照刷新存在失败子步（failed=true）：${steps.filter((s) => !s.ok).map((s) => `${s.name}: ${s.detail}`).join(" | ")}\n${body}`
+          : body,
+      )
+    } catch (e) { return fail(e) }
+  })
 }

package/templates/core/scripts/mcp-server/tools/plan-lifecycle.ts

@@ -0,0 +1,219 @@
+/*
+ * Plan 生命周期工具（2026-09-21 Plan `add-coder-plan-close-entry-plan-v1`）
+ *
+ * `plan_update` —— Plan 关闭/重开的**唯一 MCP 入口**（此前库层 transitionPlanLifecycle 齐备但零调用方：
+ * add-coder 库 36 条 ACTIVE 从未关闭；farm-agent 的 2 次关闭靠一次性脚本/人工改库，且无审计）。
+ *
+ * 语义边界（人类 2026-09-21 决策，写死在这里避免混用）：
+ * - `round` = **施工轮次**（既有 PlanRound）：每轮原子实施完成由 plan_round_close 递增，跨重开全局单调；
+ * - `reopenCycle` = **重开代数**：每次 CLOSED→REOPENED 递增，只在 `PLAN_REOPENED` 审计里出现，不参与轮次；
+ * - `REOPENED` 是**瞬态**：PUL（Policy-Update-Loop）重开后完成新一轮 Step 0 即回 `ACTIVE`；
+ *   恢复路径固定为 plan_status + 上一轮 handoff + query_audit_logs(PLAN_REOPENED) → 只补受策略影响的增量 Task。
+ */
+import * as z from "zod/v4"
+import type { ToolRegistrar } from "./registrar.js"
+import { textResponse, errorResponse } from "../shared/response.js"
+import { prisma } from "../shared/prisma.js"
+import { getRuntimeContext } from "../shared/env.js"
+import { PlanLifecycleStatusSchema, type PlanLifecycleStatus } from "../shared/plan-lifecycle.js"
+import { transitionPlanLifecycle } from "../shared/plan-lifecycle-mutation.js"
+import { writeDevOperation } from "../shared/dev-operation.js"
+
+interface PlanRowLite {
+  lifecycle: PlanLifecycleStatus
+  revision: number
+  totalTasks: number
+  doneTasks: number
+}
+
+export interface UpdatePlanLifecycleParams {
+  planName: string
+  target: PlanLifecycleStatus
+  reason?: string | null
+  policyRef?: string | null
+  force?: boolean
+  expectedRevision?: number
+}
+
+export interface UpdatePlanLifecycleResult {
+  ok: boolean
+  /** ok=false 时的拒绝原因（前置校验/不存在等），供工具与脚本共用同一措辞 */
+  error?: string
+  from?: PlanLifecycleStatus
+  to?: PlanLifecycleStatus
+  revision?: number
+  idempotent?: boolean
+  forced?: boolean
+  blockers?: string[]
+  /** lastClosedRound = null 表示未知（无 PlanRound 表且审计里无 ROUND_CLOSED），不编造 0 */
+  reopen?: { reopenCycle: number; lastClosedRound: number | null; policyRef: string | null } | null
+  audit?: { ok: boolean; detail: string }
+}
+
+/**
+ * 上次施工轮次（重开时要写进审计：上次停在第几轮）。
+ * 优先读 PlanRound 表；当前 add.prisma **未定义 PlanRound 模型**（本轮实测 planRound delegate 不存在）⇒
+ * 回退到审计：取该 Plan 最近一条 `ROUND_CLOSED` 的 afterState.round；都没有则返回 null（**显式未知**，不编 0）。
+ */
+async function resolveLastClosedRound(
+  database: typeof prisma,
+  context: ReturnType<typeof getRuntimeContext>,
+  planName: string,
+): Promise<number | null> {
+  const delegate = (database as unknown as {
+    planRound?: { findFirst(a: unknown): Promise<unknown> }
+  }).planRound
+  if (delegate) {
+    const row = (await delegate.findFirst({
+      where: { projectKey: context.projectKey, planName },
+      orderBy: { round: "desc" },
+    })) as { round?: number } | null
+    return row?.round ?? 0
+  }
+  const rec = (await database.devOperation.findFirst({
+    where: {
+      projectKey: context.projectKey,
+      producerAdapterKey: context.adapterKey,
+      planKeyword: planName,
+      action: "ROUND_CLOSED",
+    },
+    orderBy: { createdAt: "desc" },
+  })) as { afterState?: { round?: number } } | null
+  return typeof rec?.afterState?.round === "number" ? rec.afterState.round : null
+}
+
+/**
+ * Plan 生命周期更新的**唯一实现**：MCP 工具 `plan_update` 与脚本 `scripts/plan-close.ts` 共用，
+ * 避免"工具一份、脚本一份"的漂移（2026-09-21 决策）。
+ */
+export async function updatePlanLifecycle(
+  database: typeof prisma,
+  context: ReturnType<typeof getRuntimeContext>,
+  params: UpdatePlanLifecycleParams,
+): Promise<UpdatePlanLifecycleResult> {
+  const { planName, target } = params
+  const scope = { projectKey: context.projectKey, adapterKey: context.adapterKey }
+  const plan = (await database.planRecord.findFirst({ where: { ...scope, planName } })) as unknown as PlanRowLite | null
+  if (!plan) return { ok: false, error: `当前 RuntimeContextKey 下不存在 Plan: ${planName}（先 plan_track 扫描入库）` }
+  if (plan.lifecycle === target) {
+    return { ok: true, from: plan.lifecycle, to: plan.lifecycle, revision: plan.revision, idempotent: true }
+  }
+
+  const blockers: string[] = []
+  if (plan.totalTasks > 0 && plan.doneTasks < plan.totalTasks) {
+    blockers.push(`tasks 未完成：${plan.doneTasks}/${plan.totalTasks}`)
+  }
+  const hitl = (await database.hitlRecord.findFirst({
+    where: { ...scope, planName, type: "PLAN" },
+    orderBy: { round: "desc" },
+  })) as unknown as { status: string } | null
+  if (!hitl) blockers.push("缺少 PLAN 类型 HITL 记录（审批链未留痕）")
+  else if (hitl.status !== "TONGYI") blockers.push(`最新 PLAN HITL 状态为 ${hitl.status}（需 TONGYI）`)
+  if (target === "REOPENED" && !params.policyRef) blockers.push("REOPENED 必须给 policyRef（PUL 追溯：哪条策略触发重开）")
+  if (blockers.length > 0 && !params.force) {
+    return {
+      ok: false,
+      error: `前置校验未通过，拒绝 ${planName} → ${target}:\n- ${blockers.join("\n- ")}\n（force 可越过，但必须给 reason）`,
+      blockers,
+    }
+  }
+  if (blockers.length > 0 && !params.reason) {
+    return { ok: false, error: `force 越过前置校验时必须提供 reason：\n- ${blockers.join("\n- ")}`, blockers }
+  }
+
+  const updated = await transitionPlanLifecycle(database as never, {
+    context,
+    planName,
+    to: target,
+    expectedRevision: params.expectedRevision,
+  })
+
+  const reopen = target === "REOPENED"
+    ? {
+        // DevOperation 的适配器列名是 producerAdapterKey（不是 PlanRecord 的 adapterKey）
+        reopenCycle: ((await database.devOperation.count({
+          where: {
+            projectKey: context.projectKey,
+            producerAdapterKey: context.adapterKey,
+            planKeyword: planName,
+            action: "PLAN_REOPENED",
+          },
+        })) as unknown as number) + 1,
+            lastClosedRound: await resolveLastClosedRound(database, context, planName),
+        policyRef: params.policyRef ?? null,
+      }
+    : null
+
+  let audit: { ok: boolean; detail: string }
+  try {
+    await writeDevOperation(database as never, {
+      context,
+      toolName: "plan_update",
+      planKeyword: planName,
+      action: `PLAN_${target}`,
+      targetType: "PLAN",
+      targetId: planName,
+      beforeState: { lifecycle: plan.lifecycle, revision: plan.revision },
+      afterState: { lifecycle: updated.lifecycle, revision: updated.revision, forced: params.force === true, blockers, ...(reopen ?? {}) },
+      reason: params.reason ?? `plan_update ${plan.lifecycle} → ${target}`,
+    })
+    audit = { ok: true, detail: "DevOperation 已写入（shared/dev-operation.ts）" }
+  } catch (e) {
+    audit = { ok: false, detail: `DevOperation 写入失败: ${e instanceof Error ? e.message : String(e)}` }
+  }
+
+  return {
+    ok: true,
+    from: plan.lifecycle,
+    to: updated.lifecycle,
+    revision: updated.revision,
+    forced: params.force === true,
+    blockers,
+    reopen,
+    audit,
+  }
+}
+
+export function registerPlanLifecycleTools(server: ToolRegistrar) {
+  const runtimeContext = getRuntimeContext()
+  const scope = { projectKey: runtimeContext.projectKey, adapterKey: runtimeContext.adapterKey }
+
+  server.registerTool("plan_update", {
+    description:
+      "更新 Plan 生命周期（关闭/重开的唯一入口，复用状态机 + 事务 + NOTIFY + 统一审计）。\n" +
+      "lifecycle 取值即真源枚举（DRAFT/ACTIVE/BLOCKED/REJECTED/CLOSED/REOPENED/ABANDONED）。\n" +
+      "注意两个状态机不要混：TONGYI/BOHUI 属审批状态机；ABANDONED = 放弃该 Plan（生命周期决定），且可逆（→ACTIVE 复活）。\n" +
+      "驳回语义：REJECTED = 不继续（BOHUI 落此态），后续可 CLOSED（归档）/ REOPENED（重启）/ ABANDONED（放弃）。\n" +
+      "幂等：已是目标态 → idempotent=true（不 bump revision、不写审计）。\n" +
+      "前置校验（默认严格）：tasks 全部完成 + 最新 PLAN HITL 为 TONGYI；force 可越过但必须给 reason（会写进审计）。\n" +
+      "REOPENED = 瞬态重开（PUL 场景）：reopenCycle 递增、policyRef 记录触发策略；round（施工轮次）不被重置。",
+    inputSchema: z.object({
+      planName: z.string().describe("Plan 名称"),
+      lifecycle: PlanLifecycleStatusSchema.optional().describe("目标生命周期状态（7 值，含 ABANDONED）"),
+      reason: z.string().optional().describe("原因（force 必填；会写入审计）"),
+      policyRef: z.string().optional().describe("PUL：触发重开的策略/规则引用（REOPENED 必填）"),
+      force: z.boolean().optional().describe("越过前置校验（必须同时给 reason）"),
+      expectedRevision: z.number().optional().describe("乐观锁：revision 不匹配则拒绝（并行会话防撞）"),
+    }),
+  }, async (args: Record<string, unknown>) => {
+    try {
+      const planName = String(args.planName ?? "")
+      if (!planName) return errorResponse("planName 必填")
+      const target = args.lifecycle as PlanLifecycleStatus | undefined
+      if (!target) return errorResponse("未传 lifecycle：本工具只做生命周期更新（进度刷新请用 plan_track）")
+      const reason = (args.reason as string | undefined)?.trim() || null
+      const policyRef = (args.policyRef as string | undefined)?.trim() || null
+      const force = args.force === true
+      const expectedRevision = args.expectedRevision as number | undefined
+
+      // 单一实现：编排（前置校验 + 迁移 + PUL 元数据 + 审计）在 updatePlanLifecycle，与脚本共用
+      const result = await updatePlanLifecycle(prisma, runtimeContext, {
+        planName, target, reason, policyRef, force, expectedRevision,
+      })
+      if (!result.ok) return errorResponse(result.error ?? "plan_update 失败")
+      return textResponse(JSON.stringify(result, null, 2))
+    } catch (e) {
+      return errorResponse(`plan_update 失败: ${e instanceof Error ? e.message : String(e)}`)
+    }
+  })
+}

package/templates/core/scripts/mcp-server/tools/plan.ts

@@ -11,6 +11,8 @@ import { getRuntimeContext } from "../shared/env.js"
 // 口径单一真源：checklist 的 [T]/[R] 统计直接复用校验层，避免 tracker 与校验器两套口径漂移
 import { checklistStats } from "../../../validation/validators/checklist.js"
 import { assertPathInRuntimeScope } from "../shared/runtime-context.js"
+// 注：Plan 生命周期工具（plan_update）落在 tools/plan-lifecycle.ts，与本文件同族但独立注册；
+// 此处不引入 transitionPlanLifecycle / writeDevOperation，避免"同能力两处实现"的错觉。
 import { resolvePlanStatus } from "../shared/plan-lifecycle.js"
 import { createPrismaPlanStatusStore } from "../shared/plan-status-store.js"
 import {