sillyspec 3.27.2 → 3.27.5

package/src/quicklog.js

@@ -32,13 +32,15 @@ const sleep = (ms) => new Promise(r => setTimeout(r, ms))
  * 与 rename 之间），相比旧实现的必现双进已可忽略。
  * @param {string} lockPath 锁文件路径（建议与被保护文件同目录）
  * @param {() => (any|Promise<any>)} fn 临界区
- * @param {{staleMs?:number, timeoutMs?:number, retryMs?:number}} opts
+ * @param {{staleMs?:number, timeoutMs?:number, retryMs?:number, content?:string}} opts
+ *   content：锁文件内容（默认 pid-randomId）。供超时报错时展示持有者语义（如 apply 锁写
+ *   {pid, changeName}）——仅展示用途，抢占/偷锁逻辑只比对内容一致性不解析语义。
  */
 export async function withFileLock(lockPath, fn, opts = {}) {
-  const { staleMs = 30000, timeoutMs = 10000, retryMs = 50 } = opts
+  const { staleMs = 30000, timeoutMs = 10000, retryMs = 50, content = null } = opts
   mkdirSync(dirname(lockPath), { recursive: true })
   const start = Date.now()
-  const myId = `${process.pid}-${randomBytes(6).toString('hex')}`
+  const myId = content || `${process.pid}-${randomBytes(6).toString('hex')}`
   let fd = null
   // 抢锁循环
   while (true) {
@@ -174,6 +176,9 @@ function buildPushPayloadFromRaw(rawBlock, { ql_id, author_raw, status, linked_c
     payload.timestamp = parts[1] || null
     payload.title = parts.slice(2).join('|').trim() || payload.title
   }
+  // 顶层标签白名单（^ 行首锚定）：D-004@v1 根因块嵌套四子字段（- 现象：/- 根因：/- 护栏：/- 证据： 列表行）
+  // 因「- 」前缀不匹配本正则——它们是根因块正文内的列表行续行，不是新顶层标签，经 lastLabel 挂载
+  // 进 body_sections[根因]（见下方 inFiles 复位注释）。顶层四字段边界解析不受影响（R-03）。
   const labelRe = /^(状态|关联变更|文件|审计|需求|根因|方案|结果)\s*[：:]\s*(.*)$/
   const bulletRe = /^-\s+(.*)$/
   let inFiles = false
@@ -190,7 +195,9 @@ function buildPushPayloadFromRaw(rawBlock, { ql_id, author_raw, status, linked_c
       else if (label === '关联变更') { payload.linked_changes = value.split(/[，,、+；;]/).map(s => s.trim()).filter(Boolean); inLinked = true; inFiles = false }
       else if (label === '文件') { if (value) payload.files.push(...value.split(/[，,、+；;]/).map(s => s.trim()).filter(Boolean).map(p => ({ path: p, note: null }))); inFiles = true; inLinked = false }
       else if (label === '审计') { /* D-8 advisory 行：只进 raw_block 不进结构化段（body_sections 不扩 schema），并阻断续行误挂 */ lastLabel = null; inFiles = false; inLinked = false }
-      else { payload.body_sections[label] = value; lastLabel = label }
+      // 进入 需求/根因/方案/结果 字段块须关闭 inFiles/inLinked 续行模式（task-07 / D-004@v1）：否则根因块内
+      // 嵌套子字段列表行（- 现象：… 等）会命中下方「文件 bullet」分支被劫进 payload.files，从根因正文截断丢失。
+      else { payload.body_sections[label] = value; lastLabel = label; inFiles = false; inLinked = false }
       continue
     }
     if (bulletRe.test(stripped) && inFiles) {
@@ -332,6 +339,37 @@ export function parseFileNotes(raw) {
     .filter(Boolean)
 }
 
+/**
+ * 校验 --file-notes 原文格式（坑 quick-file-notes-format-silent，2026-08-24 用户反馈二期②：
+ * 多文件分隔符是 `||` 双竖线，写错成 `|`/`,` 时整段被当成第一个文件的括注静默落盘，只能手工修
+ * QUICKLOG）。命令入口 fail-fast 用：每个 `||` 段必须是 `path::括注`（`::` 必填，括注可空）；
+ * 括注内再出现 `::` 视为疑似漏写 `||` 分隔符。返回问题清单供调用方拼报错。
+ * @param {string} raw
+ * @returns {{ ok: boolean, problems: Array<{ seg: string, reason: string, hint: string }> }}
+ */
+export function validateFileNotesFormat(raw) {
+  const problems = []
+  if (!raw) return { ok: true, problems }
+  for (const seg of String(raw).split('||')) {
+    const s = seg.trim()
+    if (!s) continue
+    const idx = s.indexOf('::')
+    if (idx === -1) {
+      problems.push({ seg: s, reason: '缺 `::` 路径/括注分隔符', hint: '格式为 path::括注；不要括注也要写 path::（括注可空）' })
+      continue
+    }
+    const path = s.slice(0, idx).trim()
+    if (!path) {
+      problems.push({ seg: s, reason: '`::` 前路径为空', hint: '格式为 path::括注' })
+      continue
+    }
+    if (s.slice(idx + 2).includes('::')) {
+      problems.push({ seg: s, reason: '括注内出现 `::`', hint: '疑似多文件漏写 `||` 分隔符（双竖线）——多文件写法：path1::括注1 || path2::括注2' })
+    }
+  }
+  return { ok: problems.length === 0, problems }
+}
+
 // 结果块必填字段（quick step3 --done --output 的结构化结果模板，见 src/stages/quick.js）。
 // 4 个必填字段标签从 manifest 同源(stage-contract-spec.js quick.result-labels),prompt 事前契约与本校验单源。
 const RESULT_REQUIRED_LABELS = getRule('quick.result-labels').data.literals
@@ -344,6 +382,8 @@ const RESULT_REQUIRED_LABELS = getRule('quick.result-labels').data.literals
  * @returns {{ ok: boolean, missing: string[] }} ok=true 通过；missing=缺失的字段名列表
  */
 export function validateQuickResult(text) {
+  // 子串包含判定：根因块含嵌套四子字段列表行（- 现象：… 等，task-07 / D-004@v1 合法形态）时，
+  // 顶层四标签仍须齐备（模板契约），嵌套行不影响判定（「- 」前缀不构成顶层标签，亦不缺字段）。
   const missing = RESULT_REQUIRED_LABELS.filter(label => !String(text || '').includes(label))
   return { ok: missing.length === 0, missing }
 }
@@ -486,6 +526,9 @@ async function checkTaskCheckbox(specBase, change, qlId) {
 // 前缀」或正则 split(/(?=需求：|根因：|方案：|结果：)/)）因前导是「/|( 等非边界字符而跳过。严格失败
 // （如真实标签前导是「，」这类弱标点）退回宽松顺序扫描（上一标签之后首次出现）。缺标签返回 null → 落单行
 // 兜底（--done 契约校验仍会拦缺字段）。残余边界：正文引用标签且前导恰好是空白/句末标点时仍可能错位。
+// task-07 / D-004@v1 声明：本切分只作用于「单行四字段压缩归一」路径，嵌套四子字段（- 现象：/- 根因：/
+// - 护栏：/- 证据： 列表行）必须以多行列表行形态写入根因块正文——按序扫描先命中顶层「根因：」标签，
+// 其后的嵌套「- 根因：」等字样落在根因字段正文内不构成新边界，无需改动三个边界函数即天然兼容（Grill C-15）。
 function isFieldBoundary(body, idx) {
   if (idx <= 0) return true
   const prev = body[idx - 1]
@@ -567,6 +610,9 @@ function flipEntryInContent(content, qlId, result, changedFiles = [], fileNotes
       if (segs) body = segs.join('\n')
     }
     // 多行结果（结构化 需求/根因/方案/结果 字段块）：逐行插入为独立字段行。
+    // 根因块嵌套四子字段（- 现象：/- 根因：/- 护栏：/- 证据： 列表行，D-004@v1 postmortem 形态）属
+    // 根因块正文：在此随多行结果逐行原样落盘（带「- 」前缀、保序含换行），不被字段边界扫描误切——
+    // 单行归一切分只认「- 」前缀之外的需求：/根因：/方案：/结果： 标签，嵌套行天然不参与边界判定。
     // 单行结果：保持「结果：<一句话>」一行，向后兼容简单用例。
     const resultLines = /\r?\n/.test(body)
       ? body.split(/\r?\n/).filter(l => l.trim() !== '')

package/src/run/command.js

@@ -23,7 +23,7 @@ import { basename, join, resolve, dirname } from 'node:path'
 import { existsSync, readdirSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs'
 import { randomBytes, randomUUID } from 'node:crypto'
 import { writeAtomicSync } from '../fs-atomic.js'
-import { resolveSpecDir, countAncestorSpecDirs, resolveChangeDir, triggerSync, getStageSteps, formatWaitOptions, checkApproval, warnApprovalUnknown, didYouMean, assertSafeChangeName, detectQuickSessionDrift, detectWorktreeSpecDrift, resolveRuntimeRoot, writePlatformPointer, checkPlatformManaged, PLATFORM_MANAGED_FILENAME } from './shared.js'
+import { resolveSpecDir, countAncestorSpecDirs, resolveChangeDir, triggerSync, getStageSteps, formatWaitOptions, checkApproval, warnApprovalUnknown, didYouMean, assertSafeChangeName, detectQuickSessionDrift, detectWorktreeSpecDrift, resolveRuntimeRoot, writePlatformPointer, checkPlatformManaged, isSelfReferentialSpecRoot, PLATFORM_MANAGED_FILENAME } from './shared.js'
 import { resolveQuickLinkedChanges } from './quick-audit.js'
 import { outputStep } from './prompt.js'
 import { completeStep, skipStep, waitStep, continueStep } from './complete.js'
@@ -319,19 +319,27 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
       try {
         const { readFileSync } = await import('fs')
         const saved = JSON.parse(readFileSync(platformOptsFile, 'utf8'))
-        if (saved.specRoot) platformOpts.specRoot = saved.specRoot
-        if (saved.runtimeRoot) platformOpts.runtimeRoot = saved.runtimeRoot
-        if (saved.workspaceId) platformOpts.workspaceId = saved.workspaceId
-        if (saved.scanRunId) platformOpts.scanRunId = saved.scanRunId
-        // 平台模式 fail-fast：文件存在但缺少 specRoot
-        if (!platformOpts.specRoot && !platformOpts.runtimeRoot) {
-          console.error(`❌ 平台模式参数文件存在但缺少 specRoot/runtimeRoot: ${platformOptsFile}`)
-          console.error('   可能原因：platform-scan.json 损坏或写入不完整')
-          console.error('   解决：重新运行首次 scan 并传入 --spec-root')
-          process.exit(2) // 环境错（平台文件损坏）→ exit 2
+        // 自指指针免疫（FR-4，变更 2026-08-23-repo-native-spec-backfill）：saved.specRoot 经
+        // realpath 解析回本地 .sillyspec（repo-native junction 回环，旧模板投毒残留）→ 整体
+        // 忽略恢复（specRoot/runtimeRoot/workspaceId/scanRunId 全不回填，platformOpts 保持
+        // 无平台参数状态），按本地模式运行——内置 sync 走本地链路，specRoot 保持本地取值链。
+        if (isSelfReferentialSpecRoot(cwd, saved.specRoot)) {
+          console.warn(`⚠️ 检测到自指平台指针（repo-native junction 回环，specRoot 指回本地 .sillyspec），已忽略并按本地模式运行: ${platformOptsFile}`)
+        } else {
+          if (saved.specRoot) platformOpts.specRoot = saved.specRoot
+          if (saved.runtimeRoot) platformOpts.runtimeRoot = saved.runtimeRoot
+          if (saved.workspaceId) platformOpts.workspaceId = saved.workspaceId
+          if (saved.scanRunId) platformOpts.scanRunId = saved.scanRunId
+          // 平台模式 fail-fast：文件存在但缺少 specRoot
+          if (!platformOpts.specRoot && !platformOpts.runtimeRoot) {
+            console.error(`❌ 平台模式参数文件存在但缺少 specRoot/runtimeRoot: ${platformOptsFile}`)
+            console.error('   可能原因：platform-scan.json 损坏或写入不完整')
+            console.error('   解决：重新运行首次 scan 并传入 --spec-root')
+            process.exit(2) // 环境错（平台文件损坏）→ exit 2
+          }
+          // 恢复成功：更新 specRoot（初始值可能是 cwd/.sillyspec，恢复后应为真实 specDir）
+          specRoot = platformOpts.specRoot || specRoot
         }
-        // 恢复成功：更新 specRoot（初始值可能是 cwd/.sillyspec，恢复后应为真实 specDir）
-        specRoot = platformOpts.specRoot || specRoot
       } catch (e) {
         console.error(`❌ 平台模式参数文件读取失败: ${platformOptsFile}`)
         console.error(`   错误: ${e.message}`)
@@ -349,12 +357,20 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   if (!platformOpts.specRoot && !platformOpts.runtimeRoot && !platformFileExists) {
     const decl = checkPlatformManaged(cwd)
     if (decl) {
-      console.error(`❌ 平台接管声明生效：本项目已由平台托管（原 specRoot: ${decl.specRoot || '(未记录)'}），但恢复指针缺失，拒绝静默回退本地模式。`)
-      console.error(`   声明文件: ${join(cwd, PLATFORM_MANAGED_FILENAME)}`)
-      console.error('   恢复：① 重跑平台 scan/init（带 --spec-root）重建指针；② 确认不再使用平台：sillyspec platform disconnect（删除接管声明）；③ 显式 --spec-dir <路径> 临时指定目录。')
-      // exit(1) 而非邻近环境错的 exit(2)：这是"状态保护阻断"（对齐 PointerUnreachableError
-      // 顶层 catch 语义），非"用法/环境错"——见 design.md §5.3 v2 复审观察 (a)
-      process.exit(1)
+      // 陈旧自指声明降级（FR-4，变更 2026-08-23-repo-native-spec-backfill）：decl.specRoot 经
+      // realpath 解析回本地 .sillyspec（repo-native junction 投毒残留、指针已被清理）→ 视为
+      // 陈旧声明，warn 后按本地模式继续（不 exit 1）——声明描述的"平台接管"物理上指向本地
+      // .sillyspec，无跨库状态分裂风险；非自指声明维持 fail-closed 原样（状态保护阻断）。
+      if (isSelfReferentialSpecRoot(cwd, decl.specRoot)) {
+        console.warn(`⚠️ 检测到陈旧的自指平台接管声明（repo-native junction 回环，原 specRoot 指回本地 .sillyspec），已降级并按本地模式运行；可 sillyspec platform disconnect 清理残留声明: ${join(cwd, PLATFORM_MANAGED_FILENAME)}`)
+      } else {
+        console.error(`❌ 平台接管声明生效：本项目已由平台托管（原 specRoot: ${decl.specRoot || '(未记录)'}），但恢复指针缺失，拒绝静默回退本地模式。`)
+        console.error(`   声明文件: ${join(cwd, PLATFORM_MANAGED_FILENAME)}`)
+        console.error('   恢复：① 重跑平台 scan/init（带 --spec-root）重建指针；② 确认不再使用平台：sillyspec platform disconnect（删除接管声明）；③ 显式 --spec-dir <路径> 临时指定目录。')
+        // exit(1) 而非邻近环境错的 exit(2)：这是"状态保护阻断"（对齐 PointerUnreachableError
+        // 顶层 catch 语义），非"用法/环境错"——见 design.md §5.3 v2 复审观察 (a)
+        process.exit(1)
+      }
     }
   }
   // 持久化 platformOpts
@@ -369,29 +385,6 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   // let：下方 worktree 副本漂移守卫命中时锚回 wt.mainSpecBase（task-05/D-03）
   let specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
 
-  // ── 本地 agent 会话日志登记 + 上报（平台会话展示用，best-effort）──
-  // 平台/daemon 模式下 SillyHub 只能看到 CLI 阶段信息，看不到本地 agent 的实际执行日志。
-  // 在此探测当前 agent 环境（Claude Code / Codex / ZCode transcript / SILLYSPEC_AGENT_LOG
-  // 覆盖），把日志本地路径登记进 <runtimeRoot>/agent-session-log.json（留底）并立即
-  // REST 上报平台（POST /api/agent-logs，与进度上报同风格；协议见
-  // docs/platform-agent-log-protocol.md）。探测不到不发不写；任何失败只 warn 一行，
-  // 绝不阻断 run 主流程。
-  try {
-    const { recordAgentLogInvocation } = await import('../agent-session-log.js')
-    const r = await recordAgentLogInvocation({
-      cwd,
-      invokedCwd,
-      platformOpts,
-      specBase,
-      // 只记 flag 名不记值（--output 等 flag 值是 agent 工作文本，不进产物）
-      command: [stageName, ...flags.filter(t => typeof t === 'string' && t.startsWith('--'))].join(' '),
-    })
-    if (r && r.isNew && r.latestLogPath) {
-      const pushNote = r.pushed === true ? '已上报平台' : r.pushed === false ? '上报失败（本地已留底）' : '本地留底'
-      console.log(`📄 本地 agent 日志已登记（${pushNote}）: ${r.latestLogPath}`)
-    }
-  } catch { /* best-effort：登记失败不影响 run 主流程 */ }
-
   // 漂移提醒:cwd 祖先链 ≥2 个 .sillyspec = monorepo 多实例,当前命中的「最近」实例
   // 可能不是用户意图的项目(如 cd 进被独立 scan 的子项目跑测试后忘回根)。
   // 平台模式 / 显式 --spec-dir 跳过(已明确指定,无歧义)。仅提醒不阻断。
@@ -424,7 +417,11 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   // ⚠️ 同 init.js：必须保护真实资产（changes/、projects/、sillyspec.db）。
   // 只在「首次」执行一次——用 cwd 下的 .sillyspec-platform-cleaned 标记文件记录已处理，
   // 后续每次 run 直接跳过，避免重复检查 + 红叉噪声（此清理不阻塞流程、不动真实资产）。
-  if (platformOpts.specRoot) {
+  // 自指守卫（FR-4，变更 2026-08-23-repo-native-spec-backfill）：显式自指 --spec-root
+  // （repo-native junction 回环）下 cwd/.sillyspec 与 specRoot 同物理目录——它就是平台
+  // 规范目录本体，绝非"旧版本残留"；跳过整个清理决策（含 marker 写入，防后续真平台
+  // 接入被误标记已清理）。否则 rmSync 会删掉 repo-native 唯一真理源并留下悬空链接。
+  if (platformOpts.specRoot && !isSelfReferentialSpecRoot(cwd, platformOpts.specRoot)) {
     const legacyDir = join(cwd, '.sillyspec')
     const cleanedMarker = join(cwd, '.sillyspec-platform-cleaned')
     if (!existsSync(cleanedMarker)) {
@@ -492,6 +489,20 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   const inputValue = getFlagValue('--input')
   if (inputValue !== null) inputText = inputValue
 
+  // quick 位置参数 → 任务描述（与 auto 模式建议的 `sillyspec run quick "需求"` 用法一致）。
+  // 旧行为静默忽略裸 token（QUICKLOG 标题回退占位）；现显式消费——跳过值类 flag 的值
+  // （--files src/a.js 的 src/a.js 不是位置参数），取第一个真位置 token。配合下方
+  // 「新会话必须带描述」启动门（坑 quick-no-input-placeholder-title）。
+  if (stageName === 'quick' && inputText === null) {
+    for (let i = 0; i < flags.length; i++) {
+      const t = flags[i]
+      if (typeof t !== 'string') continue
+      if (t.startsWith('--')) { if (VALUE_FLAGS.has(t)) i++; continue }
+      inputText = t
+      break
+    }
+  }
+
   // 解析 --linked-changes <a,b|none>（quick 专用：显式声明关联变更，CI/脚本友好）
   // 与 --change 解耦：--linked-changes 语义清晰（关联变更），不与「指定变更名」混淆。
   // null = 未指定（走持久化/交互/兼容回退）；[] = 显式 none（不关联）；[...] = 显式列表
@@ -546,6 +557,7 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   const QUICK_SID_RE = /^quick-[0-9a-f]{8}$/
   let quickSessionId = null
   let quickFallbackUsed = false  // Q7: --done 未带 --change 时 fallback 读 current-quick-run-id 命中（区别于显式 --change quick-<hex>）
+  let quickSidFresh = false      // 本轮刚生成全新 sessionId（非 --change 精确恢复 / 非 fallback）——供下方「新会话必须带 --input」门判定
   if (stageName === 'quick') {
     // 1373-1376 已把 quick 的 --change 值清进 linkedChanges、changeName 置 null。
     // 此处回看 --change 原始值：若恰好是单个 quick-<8hex> → 识别为本会话 sessionId（精确恢复），
@@ -574,6 +586,7 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
       }
       if (!quickSessionId) {
         quickSessionId = 'quick-' + randomUUID().slice(0, 8)
+        quickSidFresh = true
       }
       changeName = quickSessionId
     } else {
@@ -582,6 +595,43 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     }
   }
 
+  // ── 本地 agent 会话日志登记 + 上报（平台会话展示用，best-effort）──
+  // 平台/daemon 模式下 SillyHub 只能看到 CLI 阶段信息，看不到本地 agent 的实际执行日志。
+  // 在此探测当前 agent 环境（Claude Code / Codex / ZCode transcript / SILLYSPEC_AGENT_LOG
+  // 覆盖），把日志本地路径登记进 <runtimeRoot>/agent-session-log.json（留底）并立即
+  // REST 上报平台（POST /api/agent-logs，与进度上报同风格；协议见
+  // docs/platform-agent-log-protocol.md）。探测不到不发不写；任何失败只 warn 一行，
+  // 绝不阻断 run 主流程。
+  // 位置（2026-08-23-agent-activity-sessions task-01）：必须在上方 changeName/quickSessionId
+  // 解析完成之后——上报携带会话化上下文 context：entry 级 changeKey/quickId（平台按
+  // (workspace, harness, entry.ctx) 聚合建会话；quick 会话 quickId 优先且与 changeKey 互斥）
+  // + body 级 hubSessionId（daemon 派发平台会话时注入 env SILLYHUB_SESSION_ID，非空才带）。
+  // 两段解析均在顶层作用域，此处统一算一次 context 两值皆可达。
+  try {
+    const isQuickSession = stageName === 'quick' && Boolean(quickSessionId)
+    const hubSessionIdEnv = typeof process.env.SILLYHUB_SESSION_ID === 'string' ? process.env.SILLYHUB_SESSION_ID.trim() : ''
+    const agentLogContext = {
+      hubSessionId: hubSessionIdEnv || null,
+      // quick 会话 → quickId（quick-<8hex> 完整原样，不剥前缀）；普通场景 → changeKey（--change 值，无则 null）
+      changeKey: isQuickSession ? null : (changeName || null),
+      quickId: isQuickSession ? quickSessionId : null,
+    }
+    const { recordAgentLogInvocation } = await import('../agent-session-log.js')
+    const r = await recordAgentLogInvocation({
+      cwd,
+      invokedCwd,
+      platformOpts,
+      specBase,
+      context: agentLogContext,
+      // 只记 flag 名不记值（--output 等 flag 值是 agent 工作文本，不进产物）
+      command: [stageName, ...flags.filter(t => typeof t === 'string' && t.startsWith('--'))].join(' '),
+    })
+    if (r && r.isNew && r.latestLogPath) {
+      const pushNote = r.pushed === true ? '已上报平台' : r.pushed === false ? '上报失败（本地已留底）' : '本地留底'
+      console.log(`📄 本地 agent 日志已登记（${pushNote}）: ${r.latestLogPath}`)
+    }
+  } catch { /* best-effort：登记失败不影响 run 主流程 */ }
+
   // quick 关联变更存在性守卫（坑 quick-change-phantom-linked）：quick 的 --change/--linked-changes
   // 被解析为关联变更后静默接受不存在的名字（quick 不建变更，链接幻影名必是笔误/语义误用——想给
   // 会话起名却传了 --change），后果是 QUICKLOG 挂悬空关联污染 change 关联图谱 + --done 时 sessionId
@@ -620,10 +670,23 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   // 解析 --file-notes "path::括注 || path::括注"（quick 专用：QUICKLOG「文件：」行落盘多行括注）。
   // 旁路注入 quicklog.js（per-process setter），不经 complete 收尾路径透传（避碰多 agent 并发改的收尾热点）。
   // completeQuicklogEntry 读后即清；不传 → '' → 回填审计到的实际文件单行（向后兼容）。
+  // 格式 fail-fast（坑 quick-file-notes-format-silent，2026-08-24）：分隔符写错（`|`/`,` 等）时
+  // 整段会被静默挤进第一个文件的括注、QUICKLOG 落盘后只能手工修——解析处直接拦。
   let quickFileNotes = ''
   const fileNotesValue = getFlagValue('--file-notes')
   if (fileNotesValue !== null) {
     quickFileNotes = fileNotesValue
+    const { validateFileNotesFormat } = await import('../quicklog.js')
+    const fv = validateFileNotesFormat(quickFileNotes)
+    if (!fv.ok) {
+      console.error(`❌ --file-notes 格式不对（${fv.problems.length} 处），已拒绝执行（旧行为会静默挤错进 QUICKLOG，只能手工修）：`)
+      for (const p of fv.problems.slice(0, 5)) {
+        console.error(`   「${p.seg.slice(0, 80)}」${p.reason}——${p.hint}`)
+      }
+      if (fv.problems.length > 5) console.error(`   …等共 ${fv.problems.length} 处`)
+      console.error('   正确格式: --file-notes "path1::括注1 || path2::括注2"（`||` 双竖线分隔多文件，`::` 分隔路径与括注）')
+      process.exit(2) // 用法错（--file-notes 格式非法）→ exit 2
+    }
   }
   setQuickFileNotes(quickFileNotes)
 
@@ -693,6 +756,22 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     process.exit(0)
   }
 
+  // 坑 quick-no-input-placeholder-title（2026-08-24 用户反馈二期①）：全新 quick 会话（上方
+  // 刚生成新 sessionId）不带 --input 且无 --linked-changes 可取标题 → 拒绝启动（exit 2）。
+  // 旧行为只 warn 提示「建议放弃重启」，占位标题「(quick 任务)」已落盘、只能 reset 重来——
+  // 语义标题要拖到最终 --done 才回填，平台「快速修复」列表全程隐藏。此刻零沉没成本（progress
+  // 行/QUICKLOG/guard 均未创建），直接拒掉最便宜。放在 --help 短路之后（help 查询不该被拦）、
+  // 任何会话副作用之前。精确恢复（--change quick-<hex>）与 done-like（--done/--reset/--cancel/
+  // --status/--skip/--reopen）不受限；--linked-changes 启动可从关联变更 proposal/design 提取标题。
+  if (stageName === 'quick' && quickSidFresh
+    && !(isDone || isStatus || isSkip || isReset || isReopen || isCancel)
+    && !inputText && !(Array.isArray(linkedChanges) && linkedChanges.length > 0)) {
+    console.error('❌ 新 quick 会话必须带 --input "<一句话任务描述>"（或 --linked-changes <a,b> 从关联变更取标题）。')
+    console.error('   不带描述启动会落「(quick 任务)」占位标题：平台「快速修复」列表隐藏占位条目、语义标题要拖到最终 --done 才回填，长任务全程不可见。')
+    console.error('   用法: sillyspec run quick --input "<一句话任务描述>" [--linked-changes <a,b>] [--files <...>]')
+    process.exit(2) // 用法错（新会话无任务描述）→ exit 2
+  }
+
   const isAuxiliary = auxiliaryStages.includes(stageName)
   // scan 元数据追踪（存储在 stageData.scanMeta 中，completeStep 通过 progress 访问）
 

package/src/run/complete-handlers.js

@@ -25,7 +25,7 @@
 import { basename, join, resolve, relative, isAbsolute } from 'node:path'
 import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, unlinkSync, rmSync } from 'node:fs'
 import { renameSyncRetry, writeAtomicSync } from '../fs-atomic.js'
-import { resolveChangeDir, resolveQuickSessionsDir, safeGit, auditQuickCompletion, triggerSync, isQuickMetadata, resolveRuntimeRoot } from './shared.js'
+import { resolveChangeDir, resolveQuickSessionsDir, safeGit, auditQuickCompletion, triggerSync, isQuickMetadata, resolveRuntimeRoot, collectOtherQuickSessionDeclarations } from './shared.js'
 import { detectConcurrentChanges, formatConcurrentWarning, resolveConcurrentAnchor } from './concurrent-detect.js'
 import { stageRegistry } from '../stages/index.js'
 import { SCAN_STATUS, POINTER_STATUS } from '../constants.js'
@@ -431,7 +431,11 @@ export async function handleArchiveConfirmStep({ stageName, steps, currentIdx, c
     console.log('⚠️  请添加 --confirm 确认归档，例如：sillyspec run archive --done --confirm --output "确认归档"')
     return { stageCompleted: false, currentIdx, nextPendingIdx: currentIdx }
   }
-  const archivedDir = await archiveChangeDirectory(pm, cwd, progress, specBase, platformOpts)
+  // 主仓互斥锁（坑 main-repo-no-mutex 二批）：archiveChangeDirectory 改主仓共享状态（目录
+  // rename + 共享 index 的 git add + marker 删除 + worktree 清理），与并行会话的 apply/cleanup
+  // 互踩。exit 钩子兜底：其内部 guard 失败 exit(1) 时锁也会被清（见 withMainRepoLock）。
+  const { withMainRepoLock } = await import('../worktree-apply.js')
+  const archivedDir = await withMainRepoLock(cwd, changeName, 'archive-finalize', () => archiveChangeDirectory(pm, cwd, progress, specBase, platformOpts))
   if (archivedDir && existsSync(archivedDir)) {
     // 内存快照同步（坑 archive-progress-show-stale，2026-08-21 实证）：archiveChangeDirectory 内
     // unregisterChange 已在 DB 写 current_stage='archive'（终态一致化），但本进程 progress 是命令
@@ -863,6 +867,11 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
         // （平台模式 resolveSpecDir(cwd) 会 miss specRoot 静默丢信号，plan 审查 gap-5）
         specBase,
         projectName: progress?.project || null,
+        // 他者 active 会话声明索引（坑 foreign-session-declared-false-block）：多 agent 并发时
+        // 并行会话 --files 声明的文件退栈归该会话审计，不再误拦本会话。与上方 guard 读取同源
+        // （resolveQuickSessionsDir 同参，平台模式 runtimeRoot 对齐）；fail-open：采集失败 → 空
+        // → 回到无豁免现状。
+        otherSessionsDeclared: collectOtherQuickSessionDeclarations(platformOpts, specBase, changeName),
       }
       review = await auditQuickCompletion(cwd, mergedGuard, { isConfirm: confirm })
       printQuickAuditReview(review)
@@ -913,8 +922,9 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
     const isLastStep = currentIdx === steps.length - 1
     if (isLastStep && !outputText) {
       console.error('\n❌ quick 最后一步 --done 必须带 --output（四字段结果模板）。')
-      console.error('   --output 是 QUICKLOG「结果：」归档的唯一来源。补全后重跑 --done（不丢进度），照抄模板：')
-      console.error('     sillyspec run quick --done --change <changeName> --output "需求：… 根因：… 方案：… 结果：…"')
+      console.error('   --output 是 QUICKLOG「结果：」归档的唯一来源。补全后重跑 --done（不丢进度），推荐四参数形式（CLI 自动合成，无嵌套冒号事故面）：')
+      console.error('     sillyspec run quick --done --change <changeName> --req "一句话语义化短标题" --cause "为什么这样改" --solution "怎么改的" --result "验证情况（测试数 / lint / typecheck / 部署状态）"')
+      console.error('   兼容旧形式：--output "需求：… 根因：… 方案：… 结果：…"')
       steps[currentIdx].status = 'pending'
       steps[currentIdx].completedAt = null
       process.exit(1)
@@ -924,7 +934,9 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
       if (!resultCheck.ok) {
         console.error('\n' + getRule('quick.result-labels').failMessage.replaceAll('${missing}', resultCheck.missing.join('、')))
         console.error(`   --output 是 QUICKLOG「结果：」归档的唯一来源，四个标签必须放在 --output 里（不是 --input）。`)
-        console.error(`   补全后重跑 --done（不丢进度），直接照抄此模板：`)
+        console.error(`   补全后重跑 --done（不丢进度）。推荐四参数形式（CLI 自动合成结构化模板，避免旧形式嵌套全角冒号被拆分判定缺字段）：`)
+        console.error(`     sillyspec run quick --done --change <changeName> --req "一句话语义化短标题（即 QUICKLOG 条目标题）" --cause "为什么这样改（纯新增/样式则写「无，纯新增/纯样式」）" --solution "怎么改的" --result "验证情况（测试数 / lint / typecheck / 部署状态）"`)
+        console.error(`   或照抄旧形式模板：`)
         console.error(`     sillyspec run quick --done --change <changeName> --output "需求：用户/任务要什么`)
         console.error(`     根因：为什么这样改（纯新增/样式则写「无，纯新增/纯样式」）`)
         console.error(`     方案：怎么改的`)
@@ -1331,22 +1343,39 @@ export async function handleExecuteWorktreeCleanup({ stageName, changeName, cwd
       } else if (meta.mode === 'native-worktree') {
         console.log('🔗 Worktree: kept (外部隔离环境)');
       } else {
-        // in-place 模式不再短路：cleanup 现在能安全处理 in-place（只清 meta，不碰主工作区）
-        const check = wm.hasUnappliedChanges(changeName);
-        if (check.hasChanges) {
-          console.log(`🔗 Worktree: pending apply (${check.changedFiles.length} 个未应用变更)`);
-          console.log(`   下一步: sillyspec worktree apply ${changeName}`);
-        } else {
-          const cleanResult = wm.cleanup(changeName);
-          console.log(`🔗 Worktree: ${cleanResult.result}`);
-          if (cleanResult.residual?.length > 0) {
-            console.warn(`   ⚠️ 清理残留: ${cleanResult.residual.join('; ')}`);
-            console.warn(`   手动处理: sillyspec worktree cleanup ${changeName} --force`);
-          } else if (cleanResult.details?.length > 0) {
-            for (const d of cleanResult.details) {
-              if (d.startsWith('⚠️')) console.log(`   ${d}`);
+        // in-place 模式不再短路：cleanup 现在能安全处理 in-place（只清 meta，不碰主工作区）。
+        // 主仓互斥锁（坑 main-repo-no-mutex 二批）：检查+清理与并行会话的 apply/cleanup 互斥
+        // （防 TOCTOU：检查时他者正在 apply → 判定漂移）。best-effort：锁超时不阻断 execute
+        // 完成，降级为保留 worktree + 手动清理指引。
+        try {
+          const { withMainRepoLock } = await import('../worktree-apply.js')
+          const cleanResult = await withMainRepoLock(cwd, changeName, 'execute-cleanup', () => {
+            const check = wm.hasUnappliedChanges(changeName);
+            if (check.hasChanges) {
+              return { kept: true, check }
+            }
+            return { kept: false, result: wm.cleanup(changeName) }
+          })
+          if (cleanResult.kept) {
+            console.log(`🔗 Worktree: pending apply (${cleanResult.check.changedFiles.length} 个未应用变更)`);
+            console.log(`   下一步: sillyspec worktree apply ${changeName}`);
+          } else {
+            console.log(`🔗 Worktree: ${cleanResult.result.result}`);
+            if (cleanResult.result.residual?.length > 0) {
+              console.warn(`   ⚠️ 清理残留: ${cleanResult.result.residual.join('; ')}`);
+              console.warn(`   手动处理: sillyspec worktree cleanup ${changeName} --force`);
+            } else if (cleanResult.result.details?.length > 0) {
+              for (const d of cleanResult.result.details) {
+                if (d.startsWith('⚠️')) console.log(`   ${d}`);
+              }
             }
           }
+        } catch (lockErr) {
+          if (/互斥锁被占用/.test(String(lockErr.message))) {
+            console.log(`🔗 Worktree 自动清理跳过（主仓互斥锁被他者会话持有）——稍后手动: sillyspec worktree cleanup ${changeName}`);
+          } else {
+            console.warn(`⚠️ worktree 清理异常（不阻断）: ${lockErr.message}`);
+          }
         }
       }
     } catch (e) {

package/src/run/complete.js

@@ -996,8 +996,11 @@ export async function waitStep(pm, progress, stageName, cwd, outputText, waitRea
   // requiresWait 语义前置（坑 archive-step3-wait-answer-hint-late）：--continue --answer 只是中继回答，
   // 本步会回到待执行（回答后还需执行动作再 --done 收尾）；不想两段式可用 --done --answer 一步完成。
   // 提示落在标记 --wait 的此刻，而非等 agent 撞 --done 报错才知道。
-  if (stepDef.requiresWait === true || currentStep.requiresWait === true) {
-    console.log(`   注：本步为 requiresWait 步骤——--continue --answer 后本步回到待执行，完成动作后需再 --done 收尾`)
+  // conditionalWait（坑 archive-subconfirm-redundant 后 archive step3 降级软门）+ repeatableWait 的
+  // --wait 同样回 pending（continueStep shouldReturnToCurrentStep），提示同样适用。
+  if (stepDef.requiresWait === true || currentStep.requiresWait === true
+    || stepDef.conditionalWait === true || currentStep.conditionalWait === true) {
+    console.log(`   注：本步为需回执的等待步骤（requiresWait/conditionalWait）——--continue --answer 后本步回到待执行，完成动作后需再 --done 收尾`)
     console.log(`   或一步完成：sillyspec run ${stageName} --done --answer "你的选择"${changeName ? ` --change ${changeName}` : ''} --output "你的摘要"`)
   }
 }

package/src/run/gates.js

@@ -463,6 +463,16 @@ function rollbackCompletionAndReturn(pm, progress, stageData, steps, currentIdx,
  */
 export async function runStageCompletionGates({ stageName, cwd, changeName, platformOpts, specBase, progress, pm, stageData, steps, currentIdx, ctx = null }) {
   const projectName = progress.project || basename(cwd)
+  // decisions.md header 自动补齐（坑 decisions-header-late-warning，2026-08-24 用户反馈二期）：
+  // brainstorm step8 旧模板自带无 frontmatter 的 decisions 样例，存量变更照抄必缺 author/created_at，
+  // 拖到平台同步/后续环节才提示。gate 前幂等补机械字段（先例：autoCheckPlanFromReviews 同层写
+  // tasks.md），validator 读到的即已补齐版——补的是 CLI 可自证的机械字段，不替 agent 产出语义内容。
+  if (['brainstorm', 'plan', 'verify'].includes(stageName) && changeName) {
+    try {
+      const { ensureDecisionDocHeader } = await import('../stage-contract.js')
+      ensureDecisionDocHeader(resolveChangeDir(cwd, changeName, platformOpts?.specRoot))
+    } catch { /* 补齐失败不阻断 gate */ }
+  }
   const contractResult = runValidators(stageName, cwd, changeName, { projectName, specRoot: platformOpts?.specRoot })
   if (contractResult.errors.length > 0) {
     console.error(`\n❌ 阶段 ${stageName} 校验失败：`)
@@ -498,6 +508,37 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
     printVerifyTestCheck(testCheck)
     if (testCheck.status === 'failed') {
       console.error('\n❌ verify 阶段被阻断：verify-result.md 自报告通过，但 CLI 实测测试失败。')
+      // 并行 WIP 归因鉴别（坑 verify-reconcile-foreign-wip）：实测跑在主仓共享工作区，并行会话
+      // 在途 WIP 物理在场——他者文件命中声明集时提示复验归因（EADDRINUSE 鉴别同款风格），不静默背锅。
+      try {
+        const { collectForeignDeclaredFiles } = await import('../verify-postcheck.js')
+        const { gitQuiet } = await import('../git-helper.js')
+        const foreignMap = collectForeignDeclaredFiles(cwd, changeName)
+        if (foreignMap.size > 0) {
+          const dirty = (gitQuiet(cwd, ['diff', '--name-only', 'HEAD']) || '')
+            .split('\n').filter(Boolean).map(f => f.replace(/\\/g, '/'))
+          const hitForeign = dirty.filter(f => foreignMap.has(f))
+          if (hitForeign.length > 0) {
+            console.error(`   ℹ️ 归因提示：主仓检出 ${hitForeign.length} 个并行会话声明的在途文件（${hitForeign.slice(0, 5).join(', ')}${hitForeign.length > 5 ? ' 等' : ''}）——实测失败可能混入他者 WIP 而非本变更问题。待其提交/收尾后复验，仍失败才是本变更的。`)
+          }
+        }
+        // 第二判据（坑 derived-artifact-stale-baseline）：本变更 apply 的文件（apply-pathspec 落盘）
+        // 与主仓近期提交重叠——本变更旧基线的生成产物可能覆盖了已合入内容，先在新基线重跑生成命令再复验
+        try {
+          const pathspecFile = join(resolveRuntimeRoot(platformOpts, specBase), `apply-pathspec-${changeName}.txt`)
+          if (changeName && existsSync(pathspecFile)) {
+            const ownFiles = new Set(readFileSync(pathspecFile, 'utf8').split('\n').map(l => l.trim()).filter(Boolean).map(f => f.replace(/\\/g, '/')))
+            if (ownFiles.size > 0) {
+              const recent = (gitQuiet(cwd, ['log', '-n', '10', '--name-only', '--pretty=format:']) || '')
+                .split('\n').map(l => l.trim().replace(/\\/g, '/')).filter(Boolean)
+              const overlap = [...new Set(recent)].filter(f => ownFiles.has(f))
+              if (overlap.length > 0) {
+                console.error(`   ℹ️ 归因提示②：本变更有 ${overlap.length} 个文件与主仓最近 10 条提交重叠（${overlap.slice(0, 5).join(', ')}${overlap.length > 5 ? ' 等' : ''}）——若为生成产物（api-types 等），本变更可能在旧基线生成并覆盖了已合入内容；先在新基线重跑生成命令（如 gen:types）再复验。`)
+              }
+            }
+          }
+        } catch { /* 判据②失败不影响主流程 */ }
+      } catch { /* 归因提示失败不影响阻断语义 */ }
       console.error('   请修复失败的测试并更新 verify-result.md 后重新完成此步骤。')
       return await rollbackCompletionAndReturn(pm, progress, stageData, steps, currentIdx, cwd, changeName, platformOpts)
     }
@@ -543,29 +584,10 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
         }
       }
     }
-    // ── verify 服务进程回收（坑 verify-service-process-leak，2026-08-21 实证：真实启动验证
-    // 起的 uvicorn 漏挂一天多）。verify prompt 要求长驻服务 PID 登记 .runtime/verify-services.pids，
-    // 此处收尾逐个 kill + 清文件。best-effort：ESRCH（已退出）静默，kill 失败 warn 不阻断 verify。
+    // ── verify 服务进程回收（坑 verify-service-process-leak；坑 verify-pids-cross-session-kill
+    // 见 reapVerifyServices 注释）──
     try {
-      const servicesPath = join(resolveRuntimeRoot(platformOpts, specBase), 'verify-services.pids')
-      if (existsSync(servicesPath)) {
-        const pids = readFileSync(servicesPath, 'utf8').split('\n').map(l => l.trim()).filter(l => /^\d+$/.test(l))
-        const reaped = []; const failed = []
-        for (const pid of pids) {
-          try { process.kill(parseInt(pid, 10), 'SIGTERM'); reaped.push(pid) }
-          catch (e) { if (e.code !== 'ESRCH') failed.push(`${pid}(${e.code || e.message})`) }
-        }
-        try { unlinkSync(servicesPath) } catch {}
-        if (reaped.length > 0) console.log(`🧹 verify 服务进程已回收 ${reaped.length} 个（PID: ${reaped.join(', ')}）`)
-        // CLI 回执（坑 verify-literal-evidence-mismatch）：回收即真实启动的结构化证据——
-        // checkIntegrationEvidence（stage-contract）读回执注入匹配，agent 措辞差异不再误拦
-        try {
-          writeFileSync(join(dirname(servicesPath), 'verify-services.receipt.json'), JSON.stringify({
-            change: changeName || null, reapedPidCount: reaped.length, reapedAt: new Date().toISOString(),
-          }, null, 2) + '\n')
-        } catch {}
-        if (failed.length > 0) console.warn(`⚠️ 服务进程回收失败 ${failed.length} 个：${failed.join(', ')} — 手动处理：taskkill /PID <pid> /F（Windows）/ kill -9 <pid>`)
-      }
+      reapVerifyServices(platformOpts, specBase, changeName)
     } catch (e) { console.warn(`⚠️ verify 服务进程回收异常（不阻断）: ${e.message}`) }
 
     console.log('\n✅ 验证通过，下一步：sillyspec run archive')
@@ -1027,3 +1049,46 @@ export async function completeStageGates({ stageName, cwd, changeName, platformO
   return null
 }
 
+
+/**
+ * verify 服务进程回收（verify --done 收尾调用）。
+ *
+ * 坑 verify-service-process-leak（2026-08-21）：真实启动验证起的长驻服务（uvicorn 等）漏挂
+ * 一天多——verify prompt 要求 PID 按变更分片登记 .runtime/verify-services-<change>.pids。
+ * 坑 verify-pids-cross-session-kill（2026-08-23）：原单文件无归属，A 会话 --done 会把 B 正在
+ * 收集 Runtime Evidence 的服务一并杀掉——分片后各回收各的；旧单文件兼容回收（升级过渡期）。
+ * 回执同样按变更分片（原单份被并行会话后写覆盖），checkIntegrationEvidence（stage-contract）
+ * 读分片名注入证据匹配。best-effort：ESRCH（已退出）静默，kill 失败 warn 不阻断 verify。
+ *
+ * @returns {{ reaped: number, receiptPath: string|null }}
+ */
+export function reapVerifyServices(platformOpts, specBase, changeName) {
+  const runtimeDir = resolveRuntimeRoot(platformOpts, specBase)
+  const reapFile = (path, label) => {
+    if (!existsSync(path)) return null
+    const pids = readFileSync(path, 'utf8').split('\n').map(l => l.trim()).filter(l => /^\d+$/.test(l))
+    const reaped = []; const failed = []
+    for (const pid of pids) {
+      try { process.kill(parseInt(pid, 10), 'SIGTERM'); reaped.push(pid) }
+      catch (e) { if (e.code !== 'ESRCH') failed.push(`${pid}(${e.code || e.message})`) }
+    }
+    try { unlinkSync(path) } catch {}
+    if (reaped.length > 0) console.log(`🧹 verify 服务进程已回收 ${reaped.length} 个${label}（PID: ${reaped.join(', ')}）`)
+    return { reaped: reaped.length, failed }
+  }
+  const own = reapFile(join(runtimeDir, `verify-services-${changeName}.pids`), '')
+  const legacy = reapFile(join(runtimeDir, 'verify-services.pids'), '（旧格式单文件，兼容回收）')
+  const reapedTotal = (own?.reaped || 0) + (legacy?.reaped || 0)
+  const failedAll = [...(own?.failed || []), ...(legacy?.failed || [])]
+  let receiptPath = null
+  if (reapedTotal > 0) {
+    try {
+      receiptPath = join(runtimeDir, `verify-services-${changeName}.receipt.json`)
+      writeFileSync(receiptPath, JSON.stringify({
+        change: changeName || null, reapedPidCount: reapedTotal, reapedAt: new Date().toISOString(),
+      }, null, 2) + '\n')
+    } catch { receiptPath = null }
+  }
+  if (failedAll.length > 0) console.warn(`⚠️ 服务进程回收失败 ${failedAll.length} 个：${failedAll.join(', ')} — 手动处理：taskkill /PID <pid> /F（Windows）/ kill -9 <pid>`)
+  return { reaped: reapedTotal, receiptPath }
+}