sillyspec 3.28.7 → 3.28.9

package/src/quicklog.js

@@ -67,6 +67,13 @@ export async function withFileLock(lockPath, fn, opts = {}) {
               if (!restored) { try { unlinkSync(claim) } catch {} }
             }
           } catch {}
+          // 偷锁重试前同样受超时与退避约束（坑 quicklog-lock-steal-spin，2026-09-12 审查批 A-③）：
+          // 旧版 continue 直接跳过下方检查——锁文件被 AV/索引器长期占用、renameSync 持续失败
+          // （每次被外层 catch 吞掉）时忙等自旋：不检查 timeoutMs、不让出 CPU，命令挂死 + 100% CPU。
+          if (Date.now() - start > timeoutMs) {
+            throw new Error(`文件锁超时（${timeoutMs}ms）: ${lockPath}`)
+          }
+          await sleep(retryMs)
           continue
         }
       } catch {}
@@ -80,7 +87,13 @@ export async function withFileLock(lockPath, fn, opts = {}) {
     return await fn()
   } finally {
     try { closeSync(fd) } catch {}
-    try { unlinkSync(lockPath) } catch {} // 释放（容忍已不存在）
+    // 释放前校验持有者身份（坑 quicklog-lock-release-mismatch，2026-09-12 审查批 A-③）：
+    // 本进程临界区超 staleMs 被他进程偷锁后，lockPath 上可能是**他人新建**的锁——无条件
+    // unlink 误删它会让第三方抢锁成功，形成双进程并发临界区。仅内容仍为本会话 myId 才删
+    // （读失败=锁已不在/被偷，容忍——偷锁路径自会回收旧 claim）。
+    try {
+      if (readFileSync(lockPath, 'utf8') === myId) unlinkSync(lockPath)
+    } catch {}
   }
 }
 
@@ -466,11 +479,17 @@ async function writeAtomic(filePath, content, opts = {}) {
   }
 }
 
-// 扫描所有 QUICKLOG-*.md（含轮转归档）当天最大 NNN + 已用 XXXX 后缀集
+// 扫描所有 QUICKLOG-*.md（含轮转归档）当天最大 NNN + 已用 XXXX 后缀集 + 当天已用全 ID 集
+// （坑 ql-id-double-occupancy 配套：全 ID 集供分配末检防整 ID 复用；容错正则见下）
 function scanExisting(quicklogDir, today) {
   let maxSeq = 0
   const usedSuffix = new Set()
+  const usedIds = new Set()
   const re = /^## ql-(\d{8})-(\d{3})-([0-9a-fA-F]{4})\b/gm
+  // 容错形态：手改/工具写入的畸形头（双空格、后缀紧贴 |）不匹配严格正则 → maxSeq 漏计 →
+  // 新分配复用同序号。第二正则只宽松空白，日期/序号/后缀结构仍须齐整；命中的序号并入
+  // maxSeq（防同序号双条目），全 ID 进 usedIds（防整 ID 复用）。引用字样（行首带前缀）不命中。
+  const reLoose = /^##[ \t]*ql-(\d{8})-(\d{3})-([0-9a-fA-F]{4})[ \t]*\|/gm
   // E22c：轮转归档按文件名日期过滤——归档名 = QUICKLOG-<user>-<YYYY-MM-DD>.md（最后条目日期），
   // 归档内全部条目 ≤ 名内日期；名内日期早于今天的归档不可能含当日条目，跳过读取
   // （O(全历史归档) → O(当日文件)，consumer 已 10 归档文件 756KB 时免全量扫描）。
@@ -480,16 +499,19 @@ function scanExisting(quicklogDir, today) {
     if (dm && dm[1] < todayDashed) continue // 早于今天的归档，必无当日条目
     let content = ''
     try { content = readFileSync(join(quicklogDir, f), 'utf8') } catch { continue }
-    let m
-    re.lastIndex = 0
-    while ((m = re.exec(content)) !== null) {
-      if (m[1] === today) {
-        maxSeq = Math.max(maxSeq, parseInt(m[2], 10))
-        usedSuffix.add(m[3].toLowerCase())
+    for (const reOne of [re, reLoose]) {
+      let m
+      reOne.lastIndex = 0
+      while ((m = reOne.exec(content)) !== null) {
+        if (m[1] === today) {
+          maxSeq = Math.max(maxSeq, parseInt(m[2], 10))
+          usedSuffix.add(m[3].toLowerCase())
+          usedIds.add(`ql-${today}-${m[2]}-${m[3].toLowerCase()}`)
+        }
       }
     }
   }
-  return { maxSeq, usedSuffix }
+  return { maxSeq, usedSuffix, usedIds }
 }
 
 // >500 行则轮转：rename QUICKLOG-<user>.md → QUICKLOG-<user>-<最后记录日期>.md
@@ -701,11 +723,128 @@ function flipEntryInContent(content, qlId, result, changedFiles = [], fileNotes
 
 // ── 对外 API ──
 
+// 他者会话 guard 预留 ql-ID 的采集阈值：超龄会话的预留不再钉序号。与 run/shared.js
+// collectOtherQuickSessionDeclarations 的 FOREIGN_SESSION_STALE_MS 同口径（7 天）——正常并发
+// 会话间隔在分钟/小时级，7 天未收尾的会话按僵尸处理。本模块不 import run 层（分层：
+// run/* → quicklog，反向会成环），阈值在此独立声明。
+const GUARD_CLAIM_STALE_MS = 7 * 24 * 60 * 60 * 1000
+
+/**
+ * 采集当前库内各 quick 会话 guard.json 已预留的 ql-ID（坑 ql-id-double-occupancy）。
+ *
+ * quick 启动在锁内追加 QUICKLOG 条目后把 ql-ID 写入 guard.json。条目随后丢失（并行 git
+ * 操作回滚未提交 QUICKLOG / worktree 分裂合并等）时，QUICKLOG 扫描看不到该预留 → 下一个
+ * 会话分配复用同一序号（suffix 再撞上即整 ID 双占用，2026-09-13 实证 007-1351、历史
+ * 2026-06-04 001-7a4c 同款）。分配期对 guard 预留让位（allocateQuicklogEntry）、--done 期
+ * 对残留占用校验（complete-handlers）都以此为准。
+ *
+ * fail-open：目录不存在/损坏 guard.json/超龄僵尸/任何异常 → 跳过或空集，采集失败回到
+ * 无预留现状（不放大让位面）。
+ *
+ * @param {string} specBase .sillyspec 根目录
+ * @param {string|null} [sessionsDirHint] quick-sessions 目录（run 层经 resolveQuickSessionsDir
+ *   解析后传入；缺省 <specBase>/.runtime/quick-sessions）
+ * @param {number} [nowMs] 当前时间戳（可注入，测试用）
+ * @returns {Map<string, string[]>} qlId → 预留该 ID 的 sessionId 列表
+ */
+/**
+ * 遍历 quick-sessions 目录，按同一僵尸窗口口径读各会话 guard.json（collectGuardReservedQuicklogIds
+ * 与 collectActiveQuickGuardFiles 共用，活跃判定勿分叉）：guard.json 损坏/缺失 → guard=null 保留
+ * 条目（消费方各自决定跳过或视为空声明）；startedAt 可解析且超 GUARD_CLAIM_STALE_MS → 僵尸剔除。
+ *
+ * @param {string} dir quick-sessions 目录
+ * @param {number} [nowMs] 当前时间戳（可注入，测试用）
+ * @returns {Array<{sessionId: string, guard: object|null}>}
+ */
+function listQuickSessionGuards(dir, nowMs = Date.now()) {
+  const out = []
+  let sessionDirs = []
+  try {
+    sessionDirs = readdirSync(dir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name)
+  } catch { return out } // 目录不存在/不可读 → 无会话
+  for (const sessionName of sessionDirs) {
+    let guard = null
+    try { guard = JSON.parse(readFileSync(join(dir, sessionName, 'guard.json'), 'utf8')) } catch { guard = null } // 损坏/缺失 → null
+    if (guard && guard.startedAt) {
+      const startedAtMs = Date.parse(guard.startedAt)
+      if (Number.isFinite(startedAtMs) && nowMs - startedAtMs > GUARD_CLAIM_STALE_MS) continue // 僵尸不活跃
+    }
+    out.push({ sessionId: sessionName, guard })
+  }
+  return out
+}
+
+export function collectGuardReservedQuicklogIds(specBase, sessionsDirHint = null, nowMs = Date.now()) {
+  const out = new Map()
+  try {
+    const dir = sessionsDirHint || join(specBase, '.runtime', 'quick-sessions')
+    for (const { sessionId, guard } of listQuickSessionGuards(dir, nowMs)) {
+      if (!guard || typeof guard.quicklogId !== 'string' || !guard.quicklogId) continue
+      if (!out.has(guard.quicklogId)) out.set(guard.quicklogId, [])
+      out.get(guard.quicklogId).push(sessionId)
+    }
+  } catch { /* fail-open：采集失败等同无预留 */ }
+  return out
+}
+
+/**
+ * 采集各活跃 quick 会话 guard.json 声明的 allowedFiles（apply 前 guard 相交预检，FR-03 / D-002@v1）。
+ *
+ * 活跃口径与 collectGuardReservedQuicklogIds 同源（listQuickSessionGuards）：guard 目录存在即活跃
+ * （quick --done 完成时清理 guard 目录，完成态天然退出），超 7 天僵尸窗口（GUARD_CLAIM_STALE_MS，
+ * 异常残留不钉死）剔除。勿用 changes.last_active 判活跃（非周期心跳，D-002）。
+ *
+ * @param {string} specBase .sillyspec 根目录
+ * @param {{ excludeChange?: string|null, sessionsDir?: string|null, nowMs?: number }} [opts]
+ *   - excludeChange：排除自身 change 的 quick 会话——sessionId == changeName（quick 会话 id 即
+ *     change 名）或 guard.linkedChanges 显式关联该 change 的协作会话（自己人，非拦截面）
+ *   - sessionsDir：quick-sessions 目录（缺省 <specBase>/.runtime/quick-sessions）
+ *   - nowMs：当前时间戳（可注入，测试用）
+ * @returns {Map<string, string[]>} sessionId → guard.allowedFiles（无 guard/无声明 → 空数组；fail-open）
+ */
+export function collectActiveQuickGuardFiles(specBase, { excludeChange = null, sessionsDir = null, nowMs = Date.now() } = {}) {
+  const out = new Map()
+  try {
+    const dir = sessionsDir || join(specBase, '.runtime', 'quick-sessions')
+    for (const { sessionId, guard } of listQuickSessionGuards(dir, nowMs)) {
+      if (excludeChange && (sessionId === excludeChange
+        || (guard && Array.isArray(guard.linkedChanges) && guard.linkedChanges.includes(excludeChange)))) continue
+      const allowed = (guard && Array.isArray(guard.allowedFiles))
+        ? guard.allowedFiles.filter(f => typeof f === 'string' && f.length > 0)
+        : []
+      out.set(sessionId, allowed)
+    }
+  } catch { /* fail-open：采集失败等同无活跃 guard（不放大拦截面） */ }
+  return out
+}
+
+/**
+ * 数某 qlId 在所有 QUICKLOG-*.md 里的条目头出现次数（--done 占用校验用）。
+ * ≥2 = 分配竞态残留已损坏记录（同 ID 双条目）；容错空白形态与 scanExisting 的 reLoose 同口径。
+ * @returns {{count: number, files: string[]}} count=命中头总数；files=「文件名×次数」列表
+ */
+export function countQuicklogEntries(specBase, qlId) {
+  const out = { count: 0, files: [] }
+  if (!qlId || typeof qlId !== 'string') return out
+  const quicklogDir = join(specBase, 'quicklog')
+  if (!existsSync(quicklogDir)) return out
+  const re = new RegExp(`^##[ \\t]*${escapeRe(qlId)}[ \\t]*\\|`, 'gm')
+  for (const f of listQuicklogFiles(quicklogDir)) {
+    let content = ''
+    try { content = readFileSync(join(quicklogDir, f), 'utf8') } catch { continue }
+    const n = (content.match(re) || []).length
+    if (n > 0) { out.count += n; out.files.push(`${f}×${n}`) }
+  }
+  return out
+}
+
 /**
  * 分配 ql-ID 并写「进行中」条目 + 关联 tasks.md。持锁、当天唯一。
+ * 分配查重（坑 ql-id-double-occupancy）：盘上当天全 ID（含容错空白形态）+ 他者活跃会话
+ * guard 预留（sessionsDir）的序号一并让位，maxSeq 取三者最大后再 +1。
  * @returns {Promise<{qlId: string}>}
  */
-export async function allocateQuicklogEntry(specBase, gitUser, { description, linkedChanges = [], allowedFiles = [] } = {}) {
+export async function allocateQuicklogEntry(specBase, gitUser, { description, linkedChanges = [], allowedFiles = [], sessionsDir = null } = {}) {
   const quicklogDir = join(specBase, 'quicklog')
   mkdirSync(quicklogDir, { recursive: true })
   // git user.name 无字符限制，可含 / \ .. 等路径元字符（git config 或 .git/config 可控）——
@@ -718,20 +857,40 @@ export async function allocateQuicklogEntry(specBase, gitUser, { description, li
   const files = Array.isArray(allowedFiles) ? allowedFiles : []
   const today = todayStamp()
 
-  return await withFileLock(lockPath, async () => {
-    const { maxSeq, usedSuffix } = scanExisting(quicklogDir, today)
+  // 平台推送在锁外执行（2026-09-11 审查性能包①）：锁内 5s 网络推送 + 逐变更 tasks 锁
+  // （最坏各 10s）可使临界区突破 30s stale 偷锁阈值——他进程偷锁后双写者并发，正是本模块
+  // 头声明要根治的并发丢更新被重新打开。推送 best-effort 不回写本地，锁外语义等同（原注释
+  // 自证），仅放弃「分配即推送」的顺序一致性（平台为 best-effort 面板，乱序窗口极小）。
+  let pushPayload = null
+  const { qlId } = await withFileLock(lockPath, async () => {
+    const { maxSeq: diskMaxSeq, usedSuffix, usedIds } = scanExisting(quicklogDir, today)
+    // 他者 guard 预留让位（坑 ql-id-double-occupancy）：同日预留序号并入 maxSeq；整 ID 进
+    // 末检集。QUICKLOG 条目丢失但 guard 仍在的窗口内，盘上扫描看不见该预留——正是
+    // 2026-09-13 007-1351 双占用的形态。
+    const claims = collectGuardReservedQuicklogIds(specBase, sessionsDir)
+    let maxSeq = diskMaxSeq
+    const claimedIds = new Set()
+    for (const [claimedId] of claims) {
+      claimedIds.add(claimedId.toLowerCase())
+      const cm = claimedId.match(/^ql-(\d{8})-(\d{3})-([0-9a-fA-F]{4})$/)
+      if (cm && cm[1] === today) maxSeq = Math.max(maxSeq, parseInt(cm[2], 10))
+    }
     const nextSeq = maxSeq + 1
-    // XXXX 4 位 hex 随机后缀（消歧；NNN 已在锁内顺序分配保证唯一，此处仅 belt-and-suspenders）
+    // XXXX 4 位 hex 随机后缀（消歧；NNN 已让位到所有已知占用之后，此处 belt-and-suspenders：
+    // usedSuffix 全日后缀避让 + 全 ID 末检，理论撞号需单日后缀空间耗尽，200 次兜底抛错）
     let suffix
+    let qlId
     let guard = 0
     do {
       suffix = randomBytes(2).toString('hex')
+      qlId = `ql-${today}-${String(nextSeq).padStart(3, '0')}-${suffix}`
       guard++
-    } while (usedSuffix.has(suffix) && guard < 100)
+    } while ((usedSuffix.has(suffix) || usedIds.has(qlId) || claimedIds.has(qlId)) && guard < 200)
+    if (usedIds.has(qlId) || claimedIds.has(qlId)) {
+      throw new Error('allocateQuicklogEntry: ql-ID 查重 200 次仍未命中空闲号（当日条目异常膨胀，请检查 quicklog/）')
+    }
 
     await rotateIfNeeded(userFile, user)
-
-    const qlId = `ql-${today}-${String(nextSeq).padStart(3, '0')}-${suffix}`
     const entry = [
       '',
       `## ${qlId} | ${nowDatetime()} | ${desc}`,
@@ -744,9 +903,7 @@ export async function allocateQuicklogEntry(specBase, gitUser, { description, li
 
     for (const c of linked) await appendTaskCheckbox(specBase, c, qlId, desc)
 
-    // 平台推送（task-06 / FR-02 / D-003）：锁外语义等同（推送不回写本地），但放锁内
-    // 保证「分配即推送」顺序一致；best-effort 失败不影响返回。
-    await pushQuicklogEntryToPlatform(specBase, {
+    pushPayload = {
       ql_id: qlId,
       timestamp: nowDatetime(),
       title: desc,
@@ -758,10 +915,13 @@ export async function allocateQuicklogEntry(specBase, gitUser, { description, li
       files: files.map(f => ({ path: f, note: null })),
       body_sections: {},
       raw_block: entry,
-    }).catch(() => {}) // pushQuicklogEntryToPlatform 自身已吞错；双保险防未来改动破坏 best-effort 契约
-
+    }
     return { qlId }
   })
+  if (pushPayload) {
+    await pushQuicklogEntryToPlatform(specBase, pushPayload).catch(() => {}) // 自身已吞错；双保险防未来改动破坏 best-effort 契约
+  }
+  return { qlId }
 }
 
 /**
@@ -785,9 +945,11 @@ export async function appendQuicklogEntryWithId(specBase, gitUser, qlId, { descr
   const linked = Array.isArray(linkedChanges) ? linkedChanges : []
   const files = Array.isArray(allowedFiles) ? allowedFiles : []
 
-  return await withFileLock(lockPath, async () => {
+  // 推送出锁（同 allocateQuicklogEntry 性能包①：临界区只留本地写 + tasks 挂载）
+  let pushPayload = null
+  const { existed } = await withFileLock(lockPath, async () => {
     // 双检（锁内）：并发兜底同 ID 只落一条
-    if (findQuicklogEntry(specBase, gitUser, qlId)) return { qlId, existed: true }
+    if (findQuicklogEntry(specBase, gitUser, qlId)) return { existed: true }
     await rotateIfNeeded(userFile, user)
     const entry = [
       '',
@@ -799,7 +961,7 @@ export async function appendQuicklogEntryWithId(specBase, gitUser, qlId, { descr
     ].join('\n')
     appendFileSync(userFile, entry)
     for (const c of linked) await appendTaskCheckbox(specBase, c, qlId, desc)
-    await pushQuicklogEntryToPlatform(specBase, {
+    pushPayload = {
       ql_id: qlId,
       timestamp: nowDatetime(),
       title: desc,
@@ -810,9 +972,13 @@ export async function appendQuicklogEntryWithId(specBase, gitUser, qlId, { descr
       files: files.map(f => ({ path: f, note: null })),
       body_sections: {},
       raw_block: entry,
-    }).catch(() => {})
-    return { qlId, existed: false }
+    }
+    return { existed: false }
   })
+  if (pushPayload && !existed) {
+    await pushQuicklogEntryToPlatform(specBase, pushPayload).catch(() => {})
+  }
+  return { qlId, existed }
 }
 
 /**
@@ -837,10 +1003,12 @@ export async function completeQuicklogEntry(specBase, gitUser, qlId, { resultTex
     ? softFiles.filter(Boolean).map((f) => String(f).replace(/\\/g, '/'))
     : []
 
+  // 推送出锁（性能包①）：终态 payload 以锁内落盘结果组装，锁外 best-effort 推送 + sidecar 持久化
+  // （sidecar 与推送同源同解析器，同移锁外不改变「以落盘终态为准」语义）
+  let finalPayload = null
   await withFileLock(lockPath, async () => {
     // 条目可能在主文件或轮转归档中
     let updatedContent = null
-    let updatedFile = null
     for (const f of listQuicklogFiles(quicklogDir)) {
       const filePath = join(quicklogDir, f)
       let content = ''
@@ -850,7 +1018,6 @@ export async function completeQuicklogEntry(specBase, gitUser, qlId, { resultTex
       if (updated !== null) {
         await writeAtomic(filePath, updated) // 命中处原子落盘（只改含目标条目的那一个文件）
         updatedContent = updated
-        updatedFile = filePath
         break
       }
     }
@@ -860,16 +1027,16 @@ export async function completeQuicklogEntry(specBase, gitUser, qlId, { resultTex
     // （design §5.3：翻完成时标题行被 extractTitleFromResult 刷新，推送须与落盘一致，
     // 不能用入参拼——标题/结果块/文件行都会在 flipEntryInContent 中重写）。
     const rawBlock = extractRawBlock(updatedContent, qlId)
-    const finalPayload = buildPushPayloadFromRaw(rawBlock, {
+    finalPayload = buildPushPayloadFromRaw(rawBlock, {
       ql_id: qlId,
       author_raw: user,
       status: 'completed',
       linked_changes: linked,
     })
-    // P1-4：终态结构 sidecar 持久化（同一解析器产出，md/sidecar 恒一致；fail-soft）
-    writeQuicklogSidecar(specBase, finalPayload)
-    await pushQuicklogEntryToPlatform(specBase, finalPayload).catch(() => {})
   })
+  // P1-4：终态结构 sidecar 持久化（同一解析器产出，md/sidecar 恒一致；fail-soft）
+  writeQuicklogSidecar(specBase, finalPayload)
+  await pushQuicklogEntryToPlatform(specBase, finalPayload).catch(() => {})
 }
 
 /**

package/src/review-dispatch.js

@@ -197,7 +197,8 @@ export function persistStageReview({ runtimeRoot, stage, changeName, reviewRunId
     const h = computeDocHash(mainDocPath)
     if (h) review.docHash = h
   }
-  const schema = validateStageReviewSchema(review)
+  // ql-20260915-001 修复③：透传 stage——schema 错误文案给本 stage 期望 reviewType
+  const schema = validateStageReviewSchema(review, stage)
   if (!schema.ok) return { ok: false, errors: schema.errors }
   review.reviewedFiles = Array.isArray(review.reviewedFiles) && review.reviewedFiles.length > 0
     ? review.reviewedFiles