sillyspec 3.27.2 → 3.27.6

package/.worktrees/8d2d0392/src/endpoint-extractor.js

@@ -0,0 +1,409 @@
+/**
+ * endpoint-extractor.js — 从代码中提取 HTTP 端点定义和调用
+ *
+ * provider 端：扫描 router 文件，提取注册的 API 路径
+ * consumer 端：扫描前端文件，提取 apiFetch/request 调用路径
+ *
+ * 契约对账时：provider 产出 ≠ consumer 消费 → gap
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs'
+import { join, extname, basename, dirname, resolve } from 'path'
+import { execSync } from 'child_process'
+
+// ─── Provider: 扫描后端 router 注册的端点 ───────────────────────────────
+
+/**
+ * matchIndex → 装饰器/路由起始行号（全文匹配配套；1-based）。
+ * 坑 endpoint-multiline-decorator-miss（2026-08-24 用户实证）：三框架提取器原为逐行匹配，
+ * 多行装饰器（`@router.get(\n  "/path",\n  response_model=…)` 等）路径不在装饰器行 → 端点
+ * 静默漏 → endpoints.json artifact 与 live 扫描双失真 → probe5 missingBackend 误报（11 个
+ * 存量端点）。装饰器匹配改为全文正则（`\s*` 天然跨换行），行号取起始行。
+ */
+function lineOfIndex(content, index) {
+  return content.slice(0, index).split('\n').length
+}
+
+/**
+ * 从单个文件提取 FastAPI router 端点
+ * 支持 APIRouter(prefix=...) 和 @router.get/post/put/delete/patch("/path")
+ *
+ * @param {string} filePath - 文件绝对路径
+ * @returns {Array<{ method: string, path: string, source: string, line: number }>}
+ */
+export function extractFastApiEndpoints(filePath) {
+  const content = readFileSync(filePath, 'utf8')
+  const lines = content.split('\n')
+  const endpoints = []
+
+  // 1. 提取 router prefix（逐行，同文件近似——维持原行为）
+  let routerPrefix = ''
+  for (const line of lines) {
+    const prefixMatch = line.match(/(?:APIRouter|router)\s*\(\s*(?:prefix\s*=\s*)?["'`]([^"'`]+)["'`]/)
+      || line.match(/\.include_router\s*\([^)]*prefix\s*=\s*["'`]([^"'`]+)["'`]/)
+    if (prefixMatch) {
+      routerPrefix = prefixMatch[1]
+    }
+  }
+
+  // 2. 装饰器全文匹配：单行 `@router.get("/path")`、分散式 `@router.get\n("/path")`、
+  //    多行参数 `@router.get(\n  "/path",\n  response_model=…)` 三态合一（\s* 跨换行）
+  const decoratorRe = /@(?:router|api_router)\.(get|post|put|delete|patch)\s*\(\s*["'`]([^"'`]+)["'`]/g
+  let m
+  while ((m = decoratorRe.exec(content)) !== null) {
+    endpoints.push({
+      method: m[1].toUpperCase(),
+      path: routerPrefix + m[2],
+      source: filePath,
+      line: lineOfIndex(content, m.index),
+    })
+  }
+
+  return endpoints
+}
+
+/**
+ * 从单个文件提取 Express（Node）路由端点。
+ * 支持 router/app.get|post|put|delete|patch("path") 与链式 router.route("path").<method>()。
+ * app.use("prefix", router) 的前缀只做同文件近似（跨文件追踪不在首版范围）。
+ *
+ * @param {string} filePath - 文件绝对路径
+ * @returns {Array<{ method: string, path: string, source: string, line: number }>}
+ */
+export function extractExpressEndpoints(filePath) {
+  const content = readFileSync(filePath, 'utf8')
+  const lines = content.split('\n')
+  const endpoints = []
+
+  // 同文件内最后一个 app.use("prefix", ...) 作为前缀近似
+  let routerPrefix = ''
+  for (const line of lines) {
+    const useMatch = line.match(/\bapp\.use\s*\(\s*["'`]([^"'`]+)["'`]/)
+    if (useMatch) routerPrefix = useMatch[1]
+  }
+
+  // 路由全文匹配（坑 endpoint-multiline-decorator-miss：`router.get(\n  "/path",\n  handler)` 同病）
+  const routeRe = /\b(?:app|router)\.(get|post|put|delete|patch)\s*\(\s*["'`]([^"'`]+)["'`]/gi
+  let m
+  while ((m = routeRe.exec(content)) !== null) {
+    endpoints.push({ method: m[1].toUpperCase(), path: routerPrefix + m[2], source: filePath, line: lineOfIndex(content, m.index) })
+  }
+
+  // 链式 .route(path).get(h).put(h) —— 同行所有 method 配上 path（跨行链式不扩面，维持逐行）
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const routeChain = line.match(/\.route\s*\(\s*["'`]([^"'`]+)["'`]/)
+    if (routeChain) {
+      const chainPath = routerPrefix + routeChain[1]
+      for (const mm of line.matchAll(/\.(get|post|put|delete|patch)\s*\(/gi)) {
+        endpoints.push({ method: mm[1].toUpperCase(), path: chainPath, source: filePath, line: i + 1 })
+      }
+    }
+  }
+
+  return endpoints
+}
+
+/**
+ * 从单个文件提取 Spring（Java）端点。
+ * 支持 @GetMapping/@PostMapping/.../@PatchMapping 与旧式 @RequestMapping(value="path", method=RequestMethod.X)；
+ * 类级 @RequestMapping("api") 前缀合并（取文件内第一个作类前缀，近似）。
+ *
+ * @param {string} filePath - 文件绝对路径
+ * @returns {Array<{ method: string, path: string, source: string, line: number }>}
+ */
+export function extractSpringEndpoints(filePath) {
+  const content = readFileSync(filePath, 'utf8')
+  const lines = content.split('\n')
+  const endpoints = []
+
+  let classPrefix = ''
+  for (const line of lines) {
+    const cm = line.match(/@RequestMapping\s*\(\s*(?:value\s*=\s*)?["'`]([^"'`]+)["'`]/)
+    if (cm) { classPrefix = cm[1]; break }
+  }
+
+  const methodMap = { get: 'GET', post: 'POST', put: 'PUT', delete: 'DELETE', patch: 'PATCH' }
+
+  // 短形式全文匹配（坑 endpoint-multiline-decorator-miss：`@GetMapping(\n  "/path"\n)` 同病）
+  const shortRe = /@(Get|Post|Put|Delete|Patch)Mapping\s*\(\s*(?:value\s*=\s*)?["'`]([^"'`]+)["'`]/gi
+  let m
+  while ((m = shortRe.exec(content)) !== null) {
+    endpoints.push({ method: methodMap[m[1].toLowerCase()], path: classPrefix + m[2], source: filePath, line: lineOfIndex(content, m.index) })
+  }
+  // 旧形式全文匹配（[^)]*? 字符类可跨行，`@RequestMapping(\n value="/p",\n method=…)` 随全文化一并覆盖）
+  const oldRe = /@RequestMapping\s*\(\s*(?:value\s*=\s*)?["'`]([^"'`]+)["'`][^)]*?method\s*=\s*RequestMethod\.(\w+)/gi
+  while ((m = oldRe.exec(content)) !== null) {
+    endpoints.push({ method: m[2].toUpperCase(), path: classPrefix + m[1], source: filePath, line: lineOfIndex(content, m.index) })
+  }
+
+  return endpoints
+}
+
+/**
+ * 从目录递归扫描后端端点（多框架）。
+ * 按扩展名分派：.py→FastAPI / .js,.ts→Express / .java→Spring。
+ * 保留 excludePatterns（向后兼容 opts）；filePattern 在多框架分派下不再适用。
+ * @param {string} dir
+ * @param {{ excludePatterns?: RegExp[] }} opts
+ * @returns {Array<{ method: string, path: string, source: string, line: number }>}
+ */
+export function scanBackendEndpoints(dir, opts = {}) {
+  // 排除清单对齐 scanFrontendApiCalls（坑 parity-scan-stale-dirs：.claude/worktrees 陈旧检出
+  // 与各类 build 产物混入端点扫描全是噪音）——backend 侧另含 __pycache__/.gradle/maven target
+  const excludePatterns = opts.excludePatterns || [
+    /^__pycache__$/, /^node_modules$/, /^\.venv$/, /^venv$/, /^\.git$/, /^\.gradle$/,
+    /^\.claude$/, /^\.vscode$/, /^\.idea$/, /^\.cursor$/, /^\.next$/, /^\.nuxt$/,
+    /^\.output$/, /^\.turbo$/, /^\.parcel-cache$/, /^coverage$/,
+    /^\.sillyspec$/, /^\.worktrees$/, /^\.d\.ts$/,
+    /^(dist|build|target|out)$/i,
+    /test/i,
+  ]
+
+  const results = []
+  if (!existsSync(dir)) return results
+
+  function walk(d) {
+    for (const entry of readdirSync(d, { withFileTypes: true })) {
+      const full = join(d, entry.name)
+      if (entry.isDirectory()) {
+        if (excludePatterns.some(p => p.test(entry.name))) continue
+        walk(full)
+      } else if (entry.isFile()) {
+        const ext = extname(entry.name).toLowerCase()
+        try {
+          if (ext === '.py') results.push(...extractFastApiEndpoints(full))
+          else if (ext === '.js' || ext === '.ts') results.push(...extractExpressEndpoints(full))
+          else if (ext === '.java') results.push(...extractSpringEndpoints(full))
+        } catch {}
+      }
+    }
+  }
+  walk(dir)
+  return results
+}
+
+// ─── Consumer: 扫描前端 API 调用路径 ─────────────────────────────────────
+
+/**
+ * 从前端文件提取 API 调用路径
+ * 支持：
+ *   apiFetch("/api/xxx")
+ *   request("/api/xxx")
+ *   axios.get("/api/xxx")
+ *   axios.post("/api/xxx")
+ *   fetch("/api/xxx")
+ *
+ * @param {string} filePath
+ * @returns {Array<{ method: string, path: string, source: string, line: number, raw: string }>}
+ */
+export function extractFrontendApiCalls(filePath) {
+  const content = readFileSync(filePath, 'utf8')
+  const lines = content.split('\n')
+  const results = []
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+
+    // Pattern 1: apiFetch<T>("/path", { method: "POST" }) — default GET
+    const apiFetchMatch = line.match(/apiFetch\s*(?:<[^>]*>)?\s*\(\s*["'`]([^"'`]+)["'`]/)
+    if (apiFetchMatch) {
+      // 检查是否有 method 字段（在后续行或同一行）
+      let method = 'GET'
+      const snippet = lines.slice(i, Math.min(i + 3, lines.length)).join(' ')
+      const methodMatch = snippet.match(/method\s*:\s*["'`](GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)["'`]/i)
+      if (methodMatch) method = methodMatch[1].toUpperCase()
+
+      results.push({
+        method,
+        path: normalizePath(apiFetchMatch[1]),
+        source: filePath,
+        line: i + 1,
+        raw: apiFetchMatch[1],
+      })
+      continue
+    }
+
+    // Pattern 2: axios.get/post/put/delete("/path")
+    const axiosMatch = line.match(/axios\.(get|post|put|delete|patch)\s*\(\s*["'`]([^"'`]+)["'`]/i)
+    if (axiosMatch) {
+      results.push({
+        method: axiosMatch[1].toUpperCase(),
+        path: normalizePath(axiosMatch[2]),
+        source: filePath,
+        line: i + 1,
+        raw: axiosMatch[2],
+      })
+      continue
+    }
+
+    // Pattern 3: fetch("/api/xxx", { method: "POST" })
+    const fetchMatch = line.match(/(?:api_?)?fetch\s*\(\s*["'`]([^"'`]+)["'`]/)
+    if (fetchMatch && !apiFetchMatch) {
+      let method = 'GET'
+      const snippet = lines.slice(i, Math.min(i + 3, lines.length)).join(' ')
+      const methodMatch = snippet.match(/method\s*:\s*["'`](GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)["'`]/i)
+      if (methodMatch) method = methodMatch[1].toUpperCase()
+
+      results.push({
+        method,
+        path: normalizePath(fetchMatch[1]),
+        source: filePath,
+        line: i + 1,
+        raw: fetchMatch[1],
+      })
+      continue
+    }
+  }
+
+  return results
+}
+
+/**
+ * 递归扫描前端目录的 API 调用
+ * @param {string} dir
+ * @param {{ filePattern?: RegExp, excludePatterns?: RegExp[] }} opts
+ * @returns {Array<{ method: string, path: string, source: string, line: number, raw: string }>}
+ */
+export function scanFrontendApiCalls(dir, opts = {}) {
+  const filePattern = opts.filePattern || /\.(ts|tsx|js|jsx)$/
+  // 排除清单（坑 parity-scan-stale-dirs，2026-08-21 实证：扫进 .claude/worktrees/agent-* 陈旧
+  // 检出与 build 产物，872 条调用全是噪音）——目录名匹配，覆盖：
+  //   版本控制/编辑器：.git .claude（含 worktrees/agent-* 陈旧检出）.vscode .idea .cursor
+  //   构建产物：dist build out .next .nuxt .output .turbo .parcel-cache coverage
+  //   依赖/运行时：node_modules .venv venv target（rust/java）__pycache__
+  //   本工具自身：.sillyspec .sillyspec-platform.json 所在 .worktrees
+  // 文件级：.d.ts 声明、*.min.js / *.bundle.js 压缩产物（正则命中即跳）
+  const excludePatterns = opts.excludePatterns || [
+    /^node_modules$/, /^\.git$/, /^\.claude$/, /^\.vscode$/, /^\.idea$/, /^\.cursor$/,
+    /^dist$/, /^build$/, /^out$/, /^\.next$/, /^\.nuxt$/, /^\.output$/, /^\.turbo$/,
+    /^\.parcel-cache$/, /^coverage$/, /^\.venv$/, /^venv$/, /^target$/, /^__pycache__$/,
+    /^\.sillyspec$/, /^\.worktrees$/, /^__tests__$/, /^\.d\.ts$/,
+  ]
+
+  const results = []
+  if (!existsSync(dir)) return results
+
+  function walk(d) {
+    for (const entry of readdirSync(d, { withFileTypes: true })) {
+      const full = join(d, entry.name)
+      if (entry.isDirectory()) {
+        if (excludePatterns.some(p => p.test(entry.name))) continue
+        walk(full)
+      } else if (entry.isFile() && filePattern.test(entry.name)) {
+        if (/\.d\.ts$/.test(entry.name)) continue
+        if (/\.min\.(js|ts)$/.test(entry.name) || /\.bundle\.(js|ts)$/.test(entry.name)) continue
+        try {
+          results.push(...extractFrontendApiCalls(full))
+        } catch {}
+      }
+    }
+  }
+  walk(dir)
+  return results
+}
+
+// ─── 路径归一化 ─────────────────────────────────────────────────────────
+
+/**
+ * 将动态路径归一化为参数占位符
+ * /api/ppm/project-plan/${id}/plan-nodes → /api/ppm/project-plan/{param}/plan-nodes
+ * /api/ppm/project-plan/:planId/plan-nodes → /api/ppm/project-plan/{param}/plan-nodes
+ * @param {string} rawPath
+ * @returns {string}
+ */
+export function normalizePath(rawPath) {
+  return rawPath
+    .replace(/\$\{[^}]+\}/g, '{param}')
+    .replace(/:\w+/g, '{param}')
+    .replace(/\$\w+/g, '{param}')
+    .replace(/\{[^}]+\}/g, '{param}')   // Spring {planId} / FastAPI {plan_id} → {param}
+}
+
+// ─── 对账 ───────────────────────────────────────────────────────────────
+
+/**
+ * 比较前端调用的路径和后端注册的端点，返回差异
+ *
+ * @param {Array<{ path: string, method: string, source: string }>} frontendCalls
+ * @param {Array<{ path: string, method: string, source: string }>} backendEndpoints
+ * @returns {{
+ *   missingBackend: Array<{ path: string, method: string, consumerFile: string, consumerLine: number }>,
+ *   unusedBackend: Array<{ path: string, method: string, providerFile: string }>
+ * }}
+ */
+export function diffApiParity(frontendCalls, backendEndpoints) {
+  // 构建 backend 注册表：归一化 path + method → endpoint
+  const backendMap = new Map()
+  for (const ep of backendEndpoints) {
+    const key = `${ep.method}:${normalizePath(ep.path)}`
+    if (!backendMap.has(key)) backendMap.set(key, ep)
+  }
+
+  const missingBackend = []
+  for (const call of frontendCalls) {
+    const key = `${call.method}:${normalizePath(call.path)}`
+    if (!backendMap.has(key)) {
+      missingBackend.push({
+        path: normalizePath(call.path),
+        method: call.method,
+        consumerFile: call.source,
+        consumerLine: call.line,
+      })
+    }
+  }
+
+  // 构建 frontend 调用表
+  const frontendSet = new Set(
+    frontendCalls.map(c => `${c.method}:${normalizePath(c.path)}`)
+  )
+
+  const unusedBackend = []
+  for (const ep of backendEndpoints) {
+    const key = `${ep.method}:${normalizePath(ep.path)}`
+    if (!frontendSet.has(key)) {
+      unusedBackend.push({
+        path: normalizePath(ep.path),
+        method: ep.method,
+        providerFile: ep.source,
+      })
+    }
+  }
+
+  return { missingBackend, unusedBackend, ok: missingBackend.length === 0 }
+}
+
+// ─── CLI 入口 ────────────────────────────────────────────────────────────
+
+/**
+ * CLI 子命令入口：sillyspec contract scan [--backend dir] [--frontend dir]
+ * 输出 JSON 格式的端点清单和对账结果
+ */
+export async function contractScan(args, cwd) {
+  const backendIdx = args.indexOf('--backend')
+  const frontendIdx = args.indexOf('--frontend')
+  const backendDir = backendIdx !== -1 && args[backendIdx + 1]
+    ? resolve(cwd, args[backendIdx + 1])
+    : resolve(cwd, 'backend')
+  const frontendDir = frontendIdx !== -1 && args[frontendIdx + 1]
+    ? resolve(cwd, args[frontendIdx + 1])
+    : resolve(cwd, 'frontend')
+
+  const backendEndpoints = scanBackendEndpoints(backendDir)
+  const frontendCalls = scanFrontendApiCalls(frontendDir)
+  const { missingBackend, unusedBackend } = diffApiParity(frontendCalls, backendEndpoints)
+
+  return {
+    backend: backendEndpoints.map(e => ({ method: e.method, path: normalizePath(e.path), file: e.source })),
+    frontend: frontendCalls.map(c => ({ method: c.method, path: normalizePath(c.path), file: c.source })),
+    missingBackend,
+    unusedBackend,
+    summary: {
+      backendEndpointCount: backendEndpoints.length,
+      frontendCallCount: frontendCalls.length,
+      missingBackendCount: missingBackend.length,
+      unusedBackendCount: unusedBackend.length,
+      ok: missingBackend.length === 0,
+    },
+  }
+}

package/.worktrees/8d2d0392/src/foreign-declared.js

@@ -0,0 +1,78 @@
+/**
+ * 他者会话显式声明文件集（坑 verify-reconcile-foreign-wip，2026-08-23 实证：verify 实测
+ * 对账在主仓共享工作区取 git diff，无 meta 回退时把并行会话在途 WIP 全量算进本变更——误
+ * 命中他者模块跑他者测试 / 他者删除进本变更删除对账误报）。
+ *
+ * 归属口径与坑 35（quick 审计豁免，run/shared 的 collectOtherQuickSessionDeclarations）
+ * 同款：只认**显式声明**——其他 quick 会话 guard.allowedFiles + 其他变更 design §6 清单；
+ * 无主文件保留参与判定（fail-closed，不放松「未声明删除/越界」的抓取底线）。
+ *
+ * 独立零环模块：被 verify-postcheck / verify-probes / contract-matrix 共用（verify-
+ * postcheck import contract-matrix，parity 侧不能反向 import verify-postcheck）。
+ */
+import { existsSync, readFileSync, readdirSync } from 'fs'
+import { join } from 'path'
+import { parseFileChangeListDetailed } from './change-list.js'
+
+/**
+ * @param {string} cwd 项目根
+ * @param {string|null} currentChangeName 本变更名（quick 会话名或 change 名，排除自身）
+ * @returns {Map<string, string[]>} file → 声明者列表（quick-<hex> 或变更名）
+ */
+export function collectForeignDeclaredFiles(cwd, currentChangeName) {
+  const foreign = new Map()
+  const add = (file, owner) => {
+    const f = String(file || '').replace(/\\/g, '/')
+    if (!f) return
+    if (!foreign.has(f)) foreign.set(f, [])
+    if (!foreign.get(f).includes(owner)) foreign.get(f).push(owner)
+  }
+  try {
+    const specBase = join(cwd, '.sillyspec')
+    // ① 其他 quick 会话的 --files 显式声明（guard.json）
+    const sessionsDir = join(specBase, '.runtime', 'quick-sessions')
+    let sessionDirs = []
+    try { sessionDirs = readdirSync(sessionsDir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name) } catch {}
+    for (const sid of sessionDirs) {
+      if (sid === currentChangeName) continue
+      try {
+        const guard = JSON.parse(readFileSync(join(sessionsDir, sid, 'guard.json'), 'utf8'))
+        for (const f of Array.isArray(guard.allowedFiles) ? guard.allowedFiles : []) add(f, sid)
+      } catch { /* 损坏/缺失跳过 */ }
+    }
+    // ② 其他变更的 design §6 清单（目录在即视为在途变更；archive/ 下不算）
+    const changesDir = join(specBase, 'changes')
+    let changeDirs = []
+    try { changeDirs = readdirSync(changesDir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name) } catch {}
+    for (const cn of changeDirs) {
+      if (cn === currentChangeName || cn === 'archive') continue
+      const designPath = join(changesDir, cn, 'design.md')
+      if (!existsSync(designPath)) continue
+      try {
+        for (const e of parseFileChangeListDetailed(designPath)) add(e.path, cn)
+      } catch { /* 清单解析失败跳过该变更 */ }
+    }
+  } catch { /* 整体异常 → 空集（等价不过滤，回到原行为） */ }
+  return foreign
+}
+
+/**
+ * 按他者声明集切分 diff 文件（collectForeignDeclaredFiles 的消费端快捷封装）。
+ * @param {string} cwd 项目根
+ * @param {string|null} currentChangeName 本变更名
+ * @param {string[]|null} diffFiles 待切分文件列表（null 透传，保持调用方 null 语义）
+ * @returns {{ own: string[]|null, foreign: Array<{file: string, owners: string[]}> }}
+ */
+export function splitOwnVsForeignDiffFiles(cwd, currentChangeName, diffFiles) {
+  if (!Array.isArray(diffFiles)) return { own: diffFiles, foreign: [] }
+  const foreignMap = collectForeignDeclaredFiles(cwd, currentChangeName)
+  if (foreignMap.size === 0) return { own: diffFiles, foreign: [] }
+  const own = []
+  const foreign = []
+  for (const f of diffFiles) {
+    const owners = foreignMap.get(String(f).replace(/\\/g, '/'))
+    if (owners) foreign.push({ file: f, owners })
+    else own.push(f)
+  }
+  return { own, foreign }
+}

package/.worktrees/8d2d0392/src/fs-atomic.js

@@ -0,0 +1,73 @@
+/**
+ * fs-atomic.js — 原子文件写 + Windows 友好的 rename 重试
+ *
+ * 用于 .runtime/*.json、pointer、guard.json 等「会被其他进程 / hook 读取」的配置文件。
+ * 保证读者要么看到旧完整内容、要么看到新完整内容，不会读到半截 JSON。
+ *
+ * 注意：DB 持久化由 node:sqlite 引擎承担（提交即落盘 sillyspec.db + WAL 侧车），
+ * 不经此处的 writeAtomicSync；sillyspec.db 不走原子写改名。
+ */
+import { writeFileSync, renameSync, unlinkSync } from 'fs';
+import { randomBytes } from 'node:crypto';
+import { dirname, basename, join } from 'path';
+
+// Windows 上杀毒 / 索引 / IDE 占用文件时，rename 偶发这些错误，短退避重试即可
+const RENAME_RETRY_CODES = ['EPERM', 'EBUSY', 'EACCES', 'ENOTEMPTY'];
+
+/** 同步退避：优先 Atomics.wait，不可用时退化忙等（仅在 rename 冲突的极端情况触发）。 */
+function sleepSync(ms) {
+  try {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+  } catch {
+    const end = Date.now() + ms;
+    while (Date.now() < end) { /* busy wait */ }
+  }
+}
+
+/**
+ * rename 带退避重试，覆盖 Windows 偶发的 EPERM/EBUSY/EACCES/ENOTEMPTY。
+ * 目录 rename 同样适用（归档移动目录时可复用）。
+ * @param {string} from
+ * @param {string} to
+ * @param {number} [retries=5]
+ */
+export function renameSyncRetry(from, to, retries = 5) {
+  let lastErr;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      renameSync(from, to);
+      return;
+    } catch (err) {
+      lastErr = err;
+      const code = err && err.code;
+      // 非可重试错误码立即抛出，不浪费时间
+      if (!code || !RENAME_RETRY_CODES.includes(code)) throw err;
+      if (attempt < retries) sleepSync(15 * (attempt + 1));
+    }
+  }
+  throw lastErr;
+}
+
+/**
+ * 原子写文本文件：同目录 tmp 写入 → rename 覆盖目标（带 Windows 退避重试）。
+ * - tmp 名含 pid，避免多进程并发写同一目标时 tmp 名碰撞（如多会话写 local.yaml）。
+ * - rename 失败时清理 tmp，避免留下孤儿 .tmp 文件。
+ * - Node 的 rename 在 Windows 上用 MoveFileEx(REPLACE_EXISTING)，可覆盖已存在目标；
+ *   EPERM 仅在文件被其他进程锁定时出现，由 renameSyncRetry 退避重试。
+ * @param {string} filePath - 目标文件绝对路径
+ * @param {string} content - 文件内容
+ */
+export function writeAtomicSync(filePath, content) {
+  const dir = dirname(filePath);
+  // pid + 随机段双因子：Windows PID 重用激进，两进程可能撞同 pid，tmp 名碰撞 rename 互相覆盖。
+  // crypto 随机源（Math.random 可预测，tmp 名被预猜中有 symlink 预放置理论面）
+  const rnd = randomBytes(6).toString('hex');
+  const tmpPath = join(dir, `.${basename(filePath)}.${process.pid}.${rnd}.tmp`);
+  writeFileSync(tmpPath, content);
+  try {
+    renameSyncRetry(tmpPath, filePath);
+  } catch (err) {
+    try { unlinkSync(tmpPath); } catch { /* tmp 可能已被 rename 走，忽略 */ }
+    throw err;
+  }
+}