sillyspec 3.27.11 → 3.28.0

package/src/run/shared.js

@@ -378,6 +378,60 @@ export function collectOtherQuickSessionDeclarations(platformOpts, localSpecBase
   return out
 }
 
+/**
+ * quick 边界 --files 追加并入（stage.js 恢复路径与 --done 收尾共用，坑
+ * quick-audit-warning-no-guidance 2026-09-03）：追加不替换、去重保序；同时点录
+ * allowedFilesHash 供同文件并发检测（文件不存在跳过——预声明将新建文件与启动时同语义）。
+ * 就地修改 guard，返回 added 清单（空数组 = 无新增，调用方免打印免持久化）。
+ */
+export function mergeQuickBoundaryFiles(guard, quickFiles, cwd) {
+  const known = new Set(guard.allowedFiles || [])
+  const added = (Array.isArray(quickFiles) ? quickFiles : []).filter((f) => f && !known.has(f))
+  if (added.length === 0) return { guard, added: [] }
+  guard.allowedFiles = [...(guard.allowedFiles || []), ...added]
+  guard.allowedFilesHash = { ...(guard.allowedFilesHash || {}) }
+  for (const f of added) {
+    try { guard.allowedFilesHash[f] = createHash('sha256').update(readFileSync(join(cwd, f))).digest('hex') }
+    catch { /* 预声明将新建的文件，与启动时 allowedFilesHash 同语义：不存在跳过 */ }
+  }
+  return { guard, added }
+}
+
+/**
+ * 空壳 quick 会话探测（坑 quick-duplicate-empty-shell，2026-09-03 用户实证：一次输出被吞
+ * → agent 误判失败重跑 → 重复空壳会话，此前只能手工 reset + 删骨架）。判定：会话目录
+ * guard 存在、7 天内启动（超龄按僵尸跳过，与 collectOtherQuickSessionDeclarations 同口径）、
+ * 进度库中该会话有步骤记录但零步骤完成（全 pending——刚起步即中断的形态）。
+ * fail-open：进度读不到/无步骤记录的会话不列（宁可漏报不误报，并行真会话不误伤）。
+ */
+export function detectEmptyShellQuickSessions(platformOpts, localSpecBase, currentSessionId, pm, cwd, nowMs = Date.now()) {
+  const out = []
+  try {
+    const sessionsDir = resolveQuickSessionsDir(platformOpts, localSpecBase)
+    let sessionDirs = []
+    try {
+      sessionDirs = readdirSync(sessionsDir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name)
+    } catch { return out }
+    for (const sessionName of sessionDirs) {
+      if (sessionName === currentSessionId) continue
+      let guard = null
+      try { guard = JSON.parse(readFileSync(join(sessionsDir, sessionName, 'guard.json'), 'utf8')) } catch { continue }
+      if (!guard || !guard.startedAt) continue
+      const startedAtMs = Date.parse(guard.startedAt)
+      if (!Number.isFinite(startedAtMs) || nowMs - startedAtMs > FOREIGN_SESSION_STALE_MS) continue
+      try {
+        const p = pm.read(cwd, sessionName)
+        if (!p || !p.stages) continue
+        const allSteps = Object.values(p.stages).flatMap((s) => (Array.isArray(s.steps) ? s.steps : []))
+        if (allSteps.length === 0) continue // 无步骤记录：无法判定空壳，不列
+        if (allSteps.some((s) => s.completedAt)) continue // 有完成步骤 = 真实在用
+        out.push({ sessionId: guard.sessionId || sessionName, startedAt: guard.startedAt })
+      } catch { continue }
+    }
+  } catch { /* fail-open：探测失败不打扰 quick 启动 */ }
+  return out
+}
+
 /**
  * 平台指针三写（单一数据源，runCommand scan 与 cmdInit 平台模式共用）。
  *
@@ -616,6 +670,38 @@ export async function triggerSync(cwd, changeName, platformOpts = {}, opts = {})
   }
 }
 
+/**
+ * 触发步骤开始上报（X3 / design §8.2，变更 2026-08-29-change-delete-closure-and-spec-pull task-13）。
+ *
+ * 步骤启动时同端点同结构补推一次 progress：CLI 状态机的步骤行 DB 侧种子是 pending，
+ * 本推送在载荷层把 current_stage 的第一个未完成步投影为 in-progress（sync.js
+ * _projectStepStart，不写 DB，--done 推送路径不受影响）。真实效果 = 平台
+ * last_pushed_at 以步骤起点刷新（投影 current_step_status 对下一个 pending 步本就
+ * 推导为 active，X3 不改变其值，只让「最后信号」时间可信，停滞判定不再失真）。
+ * 与 triggerSync 同款契约：quick 会话降级跳过（无 progress 实体）、未连接平台在
+ * sync() 内部静默跳过、8s 总熔断（raceWithAbort + abort 在飞请求）、失败只 warn 不抛。
+ *
+ * 接线说明（本变更 allowed_paths 约束）：步骤 prompt 渲染点（run/stage.js outputStep
+ * 前段 / run/prompt.js）不在本变更可改文件集内——本导出即「步骤开始钩子」本体，
+ * 渲染侧一行 `triggerStepStartSync(cwd, changeName, platformOpts)` 的接线由后续
+ * 变更补上；execute 阶段的任务粒度信号已由 X4（stages/execute.js Wave prompt
+ * 每任务上报指引）覆盖。
+ */
+export async function triggerStepStartSync(cwd, changeName, platformOpts = {}, opts = {}) {
+  try {
+    const tsSpecBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
+    if (changeName && QUICK_SID_RE.test(changeName) && !existsSync(join(tsSpecBase, 'changes', changeName))) {
+      return // quick 会话无 progress 实体（与 triggerSync 同判），无步骤可报
+    }
+    // shared.js 在 src/run/，sync.js 在 src/ → 退一层
+    const syncMod = await import('../sync.js')
+    await raceWithAbort((sig) => syncMod.sync(changeName, cwd, { ...sig, stepStart: true }), opts.timeoutMs)
+  } catch (e) {
+    // Best Effort：步骤开始上报失败不影响主流程（下次 --done 的 triggerSync 兜底）
+    console.warn('⚠️ 步骤开始上报失败:', e.message)
+  }
+}
+
 /**
  * 自动 pull 节流（体检 PERF-02）：triggerPull/triggerPullActiveChange 在每条 stage 命令
  * 启动时注入，agent 命令往往是秒级连发——每次都发 HTTP GET（daemon 挂/慢时单命令最多

package/src/run/stage.js

@@ -19,7 +19,7 @@
 import { join, dirname } from 'node:path'
 import { existsSync, readdirSync, readFileSync, mkdirSync } from 'node:fs'
 import { writeAtomicSync } from '../fs-atomic.js'
-import { resolveSpecDir, resolveChangeDir, resolveRuntimeRoot, resolveQuickSessionsDir, triggerSync, safeGit, parsePorcelainPath, formatWaitOptions, checkApproval, getStageSteps, warnApprovalUnknown, predictProtectedQuickFiles } from './shared.js'
+import { resolveSpecDir, resolveChangeDir, resolveRuntimeRoot, resolveQuickSessionsDir, triggerSync, safeGit, parsePorcelainPath, formatWaitOptions, checkApproval, getStageSteps, warnApprovalUnknown, predictProtectedQuickFiles, mergeQuickBoundaryFiles, detectEmptyShellQuickSessions } from './shared.js'
 import { computeScanProfile, applyScanProfileSteps, executeScanPreflight, executeScanPostcheck } from './scan-profile.js'
 import { outputStep, collectStageWaitHistory } from './prompt.js'
 import { allocateQuicklogEntry, deriveTitleFromLinkedChange, sanitizeDesc } from '../quicklog.js'
@@ -350,12 +350,12 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
       progress.quickGuard = existingGuard
       // 中途追加边界：会话中途发现要改启动声明外的文件，此前 resume 会把 --files 静默丢弃、
       // 边界冻结在启动时刻，只能靠事后归属/审计行兜底。恢复时带 --files 即并入 allowedFiles
-      // （追加不替换、去重保序），同时点录 allowedFilesHash 供同文件并发检测（文件不存在跳过，
-      // 与启动同语义）。--done 审计直读 guard.json（complete-handlers §4.6），追加即被归属消费。
+      // （追加不替换、去重保序，mergeQuickBoundaryFiles 与 --done 收尾路径同源），同时点录
+      // allowedFilesHash 供同文件并发检测（文件不存在跳过，与启动同语义）。--done 审计直读
+      // guard.json（complete-handlers §4.6），追加即被归属消费。
       const resumeFiles = Array.isArray(quickOpts?.quickFiles) ? quickOpts.quickFiles.filter(Boolean) : []
       if (resumeFiles.length > 0) {
-        const known = new Set(progress.quickGuard.allowedFiles || [])
-        const added = resumeFiles.filter(f => !known.has(f))
+        const { added } = mergeQuickBoundaryFiles(progress.quickGuard, resumeFiles, cwd)
         if (added.length > 0) {
           // 受保护文件预告（坑 quick-protected-late-hint）：追加声明若含审计将拦的文件，
           // 追加时即点破（省一轮跑到 --done 才发现）。--files 只声明归属，不解锁拦截。
@@ -364,12 +364,6 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
             forceBaseline: quickOpts?.isForceBaseline || false,
           })
           if (protectedPreview.length > 0) warnProtectedQuickFiles(protectedPreview)
-          progress.quickGuard.allowedFiles = [...(progress.quickGuard.allowedFiles || []), ...added]
-          progress.quickGuard.allowedFilesHash = { ...(progress.quickGuard.allowedFilesHash || {}) }
-          for (const f of added) {
-            try { progress.quickGuard.allowedFilesHash[f] = createHash('sha256').update(readFileSync(join(cwd, f))).digest('hex') }
-            catch { /* 预声明将新建的文件，与启动时 allowedFilesHash 同语义：不存在跳过 */ }
-          }
           writeAtomicSync(guardFile, JSON.stringify(progress.quickGuard, null, 2))
           console.log(`🛡️ quick 边界已追加: ${added.length} 个文件（累计 ${progress.quickGuard.allowedFiles.length} 个）: ${added.join(', ')}`)
         }
@@ -451,6 +445,19 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
         if (allowDelete) parts.push('允许删除文件')
         console.log(`🛡️ quick 变更边界已记录: ${parts.join(', ')}`)
         console.log(`📝 QUICKLOG 条目已创建: ${qlId}`)
+        // 空壳会话探测（坑 quick-duplicate-empty-shell，2026-09-03 用户实证：一次输出被吞 →
+        // agent 误判失败重跑 → 重复空壳会话，此前只能手工 reset + 删骨架）。新会话起步时点名
+        // 他者「已启动但零步骤完成」的会话 + 给官方清理口 --cancel（QUICKLOG 翻已取消 + 挂载行
+        // 移除）。advisory 不阻断：真在用的并行会话不受影响（有完成步骤即不列）。
+        try {
+          const shells = detectEmptyShellQuickSessions(platformOpts, specBase, changeName, pm, cwd)
+          if (shells.length > 0) {
+            console.warn('')
+            console.warn(`🧹 检测到 ${shells.length} 个疑似空壳 quick 会话（已启动但零步骤完成——常见于输出中断后误重启的残留）：`)
+            for (const s of shells) console.warn(`   - ${s.sessionId}（启动于 ${s.startedAt}）`)
+            console.warn(`   清理：sillyspec run quick --cancel --change <会话ID>；若确在用请忽略本提示。`)
+          }
+        } catch { /* fail-open：探测失败不打扰 quick 启动 */ }
         // 缺 --input 且关联变更无可提取标题 → 条目落「(quick 任务)」占位标题，平台「快速修复」列表
         // 默认隐藏进行中占位（task-06 口径），长会话全程不可见、语义标题要到最终 --done 才回填。
         // 此刻会话刚起步零沉没成本，提示放弃重启带 --input 是最便宜的自愈点。

package/src/spec-sync.js

@@ -16,7 +16,7 @@
  */
 
 import { createHash } from 'crypto';
-import { existsSync, readdirSync, readFileSync, statSync, mkdirSync, writeFileSync } from 'fs';
+import { existsSync, readdirSync, readFileSync, statSync, mkdirSync, writeFileSync, unlinkSync } from 'fs';
 import { join, relative, sep } from 'path';
 
 // 与 sillyhub-daemon/src/spec-sync.ts 共用排除口径（task-07 / FR-06 / D-008@v2）：
@@ -323,6 +323,123 @@ function writeLastSyncTs(specRoot) {
   } catch { /* 标记失败只损失下次的防回推过滤，不影响本次同步结果 */ }
 }
 
+// 本地内容基线快照（坑 quicksync-conflict-granularity，2026-09-03 实证）：
+// 上次成功同步时刻的**本地文件 hash 全集**。「本地未改动」的内容级判据——
+// filterStaleUpdates 的 mtime 启发式会被 git 操作（pull/checkout/归档重写）刷新
+// mtime 击穿（本地 164 个旧归档全部伪装成「刚改过」，重试路径把陈旧副本静默
+// 推上服务器=回退）。hash 基线免疫 mtime 刷新：内容没变就是没改，服务器前进
+// 属正常多端演进 → 跟随服务器（不发 op、冲突时自动消解），只有内容真变了的
+// 文件才进冲突人工裁决。语义锚定「local at last sync」而非「server at last sync」：
+// 判据只回答「本地是否改过」，与服务器无关（bundle 拉回的新内容与快照不同 →
+// 视为本地改动照推，服务器同内容豁免兜底，无副作用）。
+const BASE_SNAPSHOT = 'spec-sync-base.json';
+
+function readBaseSnapshot(specRoot) {
+  try {
+    const raw = readFileSync(join(specRoot, '.runtime', BASE_SNAPSHOT), 'utf8');
+    const hashes = JSON.parse(raw).hashes;
+    return hashes && typeof hashes === 'object' ? hashes : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeBaseSnapshot(specRoot, localFiles) {
+  try {
+    const hashes = {};
+    for (const f of localFiles) hashes[f.path] = f.hash;
+    mkdirSync(join(specRoot, '.runtime'), { recursive: true });
+    writeFileSync(join(specRoot, '.runtime', BASE_SNAPSHOT), JSON.stringify({ ts: Date.now(), hashes }, null, 2) + '\n', 'utf8');
+  } catch { /* 快照失败只损失下次的内容级防回推，不影响本次同步结果 */ }
+}
+
+/**
+ * 丢弃「跟随服务器」型 update op（坑 quicksync-conflict-granularity ①）。
+ *
+ * 判据：本地文件 hash 与基线快照一致 = 自上次同步内容未变——此刻与服务器 hash
+ * 不同只可能是他端会话推进了服务器，本地是陈旧副本，推送即回退（spec-sync-
+ * parallel-stale-overwrite 同族，但 mtime 免疫）。与 filterStaleUpdates 互补：
+ * 快照覆盖内容级判定，mtime 兜底快照缺失（首次同步/快照损坏）的过渡期。
+ * 快照无该路径（新文件/过渡期）→ 保留 op 维持旧行为。
+ *
+ * @param {Array} ops computeSpecOps 产物
+ * @param {Array} localFiles hashFiles 产物
+ * @param {object|null} baseHashes 基线快照 { [path]: hash }；null → 不过滤
+ * @returns {{ ops: Array, followed: string[] }}
+ */
+export function dropFollowServerUpdates(ops, localFiles, baseHashes) {
+  if (!baseHashes || !Array.isArray(ops) || ops.length === 0) {
+    return { ops, followed: [] };
+  }
+  const hashByPath = new Map(localFiles.map((f) => [f.path, f.hash]));
+  const followed = [];
+  const kept = [];
+  for (const op of ops) {
+    if (op.op === 'update') {
+      const base = baseHashes[op.path];
+      const loc = hashByPath.get(op.path);
+      if (base !== undefined && loc !== undefined && base === loc) {
+        followed.push(op.path);
+        continue;
+      }
+    }
+    kept.push(op);
+  }
+  return { ops: kept, followed };
+}
+
+/**
+ * 冲突路径分流（坑 quicksync-conflict-granularity ②）：服务器 conflict 回告的路径里，
+ * 区分「本地未改动 → 自动跟随服务器」与「本地真改动 → 需人工裁决」。
+ * follower 判据 = 内容基线命中（hash 级）或 mtime 兜底（filterStaleUpdates 同款）。
+ * @returns {{ followers: string[], real: object }} real = { [path]: server_version }
+ */
+export function partitionConflictPaths(serverVersions, localFiles, baseHashes, lastSyncTs) {
+  const hashByPath = new Map(localFiles.map((f) => [f.path, f.hash]));
+  const mtimeByPath = new Map(localFiles.map((f) => [f.path, f.mtime]));
+  const followers = [];
+  const real = {};
+  for (const [path, version] of Object.entries(serverVersions || {})) {
+    const base = baseHashes?.[path];
+    const loc = hashByPath.get(path);
+    const mtime = mtimeByPath.get(path);
+    const contentUnchanged = base !== undefined && loc !== undefined && base === loc;
+    const mtimeStale = mtime !== undefined && lastSyncTs && mtime * 1000 + 1000 <= lastSyncTs;
+    if (contentUnchanged || mtimeStale) followers.push(path);
+    else real[path] = version;
+  }
+  return { followers, real };
+}
+
+/**
+ * 未决 spec 树冲突同集判定（坑 spec-sync-conflict-banner-spam）：读 .runtime 下该变更的
+ * 冲突文件，conflicting_paths 与本轮真冲突集完全一致 → 重复轮次（横幅单行降噪依据）。
+ * 文件缺失/损坏/集合增减 → false（按首报或集变化处理，全幅横幅+重写文件）。
+ */
+function isSamePendingSpecConflict(specRoot, changeName, realPaths) {
+  try {
+    const raw = readFileSync(join(specRoot, '.runtime', `spec-sync-conflict-${changeName}.json`), 'utf8');
+    const prev = JSON.parse(raw).conflicting_paths;
+    if (!Array.isArray(prev) || prev.length !== realPaths.length) return false;
+    const prevSet = new Set(prev);
+    return realPaths.every((p) => prevSet.has(p));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 清残留未决冲突标记（坑 spec-sync-conflict-banner-spam）：本轮同步无冲突 = 此前的
+ * spec 树冲突已不存在（对端停推后 last-writer-wins 收敛/本地覆盖成功），残留文件会让
+ * status 永久红标、每轮横幅去重单行提示不消。best-effort，失败只影响下一轮横幅形态。
+ */
+function clearSpecConflictMarker(specRoot, changeName) {
+  try {
+    const p = join(specRoot, '.runtime', `spec-sync-conflict-${changeName}.json`);
+    if (existsSync(p)) unlinkSync(p);
+  } catch { /* 清理失败不影响同步结果 */ }
+}
+
 /**
  * 同步本地 .sillyspec 树到平台（CLI 直跑增量同步入口）。
  *
@@ -369,15 +486,29 @@ export async function syncSpecTree(specRoot, platform, changeName, opts = {}) {
   const localFiles = hashFiles(entries);
   let ops = computeSpecOps(serverManifest, localFiles);
 
-  // 旧副本回推防护（并行会话一致性）：上次同步后本地从未改动的文件不回推覆盖服务器新内容
+  // 旧副本回推防护（并行会话一致性）：上次同步后本地从未改动的文件不回推覆盖服务器新内容。
+  // 双层判据（坑 quicksync-conflict-granularity）：内容基线快照（hash 级，免疫 git 操作刷新
+  // mtime——pull/checkout/归档重写后的旧文件内容未变即「未改动」）为主，mtime 启发式兜底
+  // 快照缺失的过渡期/新文件。forcePush（resolve --keep-local 强制重推）全旁路——用户显式
+  // 裁决「以本地为准」时本地意志高于跟随服务器语义，不得被防回推削掉。
   const lastSyncTs = readLastSyncTs(specRoot);
-  const filtered = filterStaleUpdates(ops, localFiles, lastSyncTs);
-  if (filtered.stale.length > 0) {
-    console.warn(
-      `[spec-sync] 拦下 ${filtered.stale.length} 个旧副本回推（本地自上次同步未改动而服务器已前进，如确需以本地为准：重存后重推）: ${filtered.stale.slice(0, 5).join(', ')}${filtered.stale.length > 5 ? ' 等' : ''}`
-    );
+  const baseHashes = readBaseSnapshot(specRoot);
+  if (!opts.forcePush) {
+    const dropped = dropFollowServerUpdates(ops, localFiles, baseHashes);
+    if (dropped.followed.length > 0) {
+      console.log(
+        `[spec-sync] ${dropped.followed.length} 个本地未改动文件自动跟随服务器（他端推进，内容未变不回推）: ${dropped.followed.slice(0, 5).join(', ')}${dropped.followed.length > 5 ? ' 等' : ''}`
+      );
+    }
+    ops = dropped.ops;
+    const filtered = filterStaleUpdates(ops, localFiles, lastSyncTs);
+    if (filtered.stale.length > 0) {
+      console.warn(
+        `[spec-sync] 拦下 ${filtered.stale.length} 个旧副本回推（本地自上次同步未改动而服务器已前进，如确需以本地为准：重存后重推）: ${filtered.stale.slice(0, 5).join(', ')}${filtered.stale.length > 5 ? ' 等' : ''}`
+      );
+    }
+    ops = filtered.ops;
   }
-  ops = filtered.ops;
 
   if (ops.length === 0) {
     debugLog(`[spec-sync] 无差异，跳过同步: ${changeName}`);
@@ -404,7 +535,43 @@ export async function syncSpecTree(specRoot, platform, changeName, opts = {}) {
       // HUB-08 冲突闭环：落 spec-sync-conflict-<change>.json（与进度 sync-conflict-* 同目录），
       // 供 platform status 列出 + platform resolve 三态处置。此前只 warn 返回，下次 sync 用
       // 同一 base_version 继续冲突循环，无人工裁决入口。
+      //
+      // 坑 quicksync-conflict-granularity（2026-09-03 实证 164 个旧归档整树冲突）：GET 清单
+      // → 全树 hash → POST 的竞态窗内他端推进，base_version 过期引发大规模「假冲突」——
+      // 这些文件本地根本没改（与本次 quick 零交集），却把冲突文件坐实、后续自动同步进
+      // resolve 流程。冲突粒度收窄：follower（本地未改动，内容基线/mtime 判定）自动跟随
+      // 服务器、不进冲突文件；服务器「冲突 op 跳过、其余照常 apply」语义下本会话真改动
+      // 已落——follower 清空即视为本轮同步成功（写基线，下次起 pre-POST 即拦）。
       const serverVersions = body.server_versions || {};
+      const { followers, real } = opts.forcePush
+        ? { followers: [], real: serverVersions }
+        : partitionConflictPaths(serverVersions, localFiles, baseHashes, lastSyncTs);
+      const realPaths = Object.keys(real);
+
+      // 冲突横幅降噪（坑 spec-sync-conflict-banner-spam，与 sync() 进度侧 2026-08-23 修法同族）：
+      // 未决 spec 树冲突存在期间，每步自动同步都会对同一批真冲突路径再撞一次——此前每轮
+      // 重写冲突文件 + 空行+全幅双线横幅（含整包 server_versions JSON dump），「已卡死不会
+      // 自愈」连环刷屏。冲突文件在且冲突集未变 = 用户已被告知：重复轮次单行提示（可见但不
+      // 吓人），不重写文件（created_at 稳定，status 红标语义不变）；冲突集变化才重写+全幅。
+      // forcePush（resolve --keep-local 刚裁决完重推）不参与去重——需真实判定与文件刷新。
+      const pendingSame = !opts.forcePush && realPaths.length > 0 && isSamePendingSpecConflict(specRoot, changeName, realPaths);
+      if (pendingSame) {
+        if (followers.length > 0) {
+          debugLog(`[spec-sync] ${followers.length} 个本地未改动文件自动跟随服务器: ${followers.slice(0, 5).join(', ')}${followers.length > 5 ? ' 等' : ''}`);
+        }
+        console.warn(`⚠️ [spec-sync] 变更 ${changeName} 存在未决 spec 树冲突（${realPaths.length} 个文件待裁决，本轮非冲突改动已照常同步）。处理：sillyspec platform resolve ${changeName} --keep-local | --take-platform | --abort`);
+        return { synced: 0, conflict: true, serverVersions: real, autoResolved: followers.length, conflictPath: join(specRoot, '.runtime', `spec-sync-conflict-${changeName}.json`), suppressed: true };
+      }
+      if (followers.length > 0) {
+        console.warn(`[spec-sync] ${followers.length} 个本地未改动文件自动跟随服务器（正常多端前进，无需人工裁决）: ${followers.slice(0, 5).join(', ')}${followers.length > 5 ? ' 等' : ''}`);
+      }
+      if (realPaths.length === 0) {
+        writeLastSyncTs(specRoot);
+        writeBaseSnapshot(specRoot, localFiles);
+        clearSpecConflictMarker(specRoot, changeName);
+        console.log(`[spec-sync] 冲突已自动消解（0 个需人工裁决；本会话改动 ${ops.length - followers.length > 0 ? '已同步' : '无差异'}）: ${changeName}`);
+        return { synced: Math.max(ops.length - followers.length, 0), conflict: false, autoResolved: followers.length };
+      }
       let conflictPath = null;
       try {
         const runtimeDir = join(specRoot, '.runtime');
@@ -414,20 +581,28 @@ export async function syncSpecTree(specRoot, platform, changeName, opts = {}) {
           change: changeName,
           kind: 'spec-tree',
           created_at: new Date().toISOString(),
-          server_versions: serverVersions,
-          conflicting_paths: Object.keys(serverVersions),
-          note: 'spec 树文件冲突（服务器版本领先于本地 diff 基线）。resolve --keep-local 以本地为准重推；--take-platform 暂不支持（平台无文件下载端点）',
+          server_versions: real,
+          conflicting_paths: realPaths,
+          auto_followed: followers,
+          note: 'spec 树文件冲突（仅列本地真改动文件；本地未改动文件已自动跟随服务器）。resolve --keep-local 以本地为准重推；--take-platform 拉平台 bundle 覆盖冲突文件（接受服务器版本，2026-09-03 起支持）',
         }, null, 2) + '\n', 'utf8');
       } catch (e) {
         console.warn(`[spec-sync] 冲突文件写入失败（冲突信息仅打印）: ${e.message}`);
       }
+      // 横幅只列前 5 个路径（截断防刷屏，坑 spec-sync-conflict-banner-spam）：逐文件服务器
+      // 版本在冲突详情文件里，不再整包 JSON.stringify dump 到终端。
+      const shownPaths = realPaths.slice(0, 5).join(', ') + (realPaths.length > 5 ? ' 等' : '');
       console.warn('');
-      console.warn(`⚠️ [spec-sync] 检测到 spec 树冲突（${Object.keys(serverVersions).length} 个文件，服务器版本: ${JSON.stringify(serverVersions)}）`);
-      console.warn(`⚠️ 处置：sillyspec platform resolve ${changeName} --keep-local | --abort（冲突详情: ${conflictPath || '(写入失败)'}）`);
-      return { synced: 0, conflict: true, serverVersions, conflictPath };
+      console.warn(`⚠️ [spec-sync] 检测到 spec 树冲突（${realPaths.length} 个文件: ${shownPaths}；逐文件服务器版本见冲突详情文件）`);
+      console.warn(`⚠️ 处置：sillyspec platform resolve ${changeName} --keep-local | --take-platform | --abort（冲突详情: ${conflictPath || '(写入失败)'}）`);
+      return { synced: 0, conflict: true, serverVersions: real, autoResolved: followers.length, conflictPath };
     }
     console.log(`[spec-sync] 已同步 ${ops.length} 个文件变更: ${changeName}`);
+    // 本轮无冲突 = 此前的未决 spec 树冲突已不存在，清残留标记（否则 status 永久红标、
+    // 横幅去重单行提示不消——坑 spec-sync-conflict-banner-spam）
+    clearSpecConflictMarker(specRoot, changeName);
     writeLastSyncTs(specRoot);
+    writeBaseSnapshot(specRoot, localFiles);
     return { synced: ops.length };
   } catch (err) {
     console.warn(`[spec-sync] 同步异常（文件树本次未同步，下次自动重试）: ${changeName}: ${err.message}`);
@@ -441,5 +616,7 @@ export default {
   computeSpecOps,
   extractChangeDirs,
   filterStaleUpdates,
+  dropFollowServerUpdates,
+  partitionConflictPaths,
   syncSpecTree,
 };

package/src/stages/archive.js

@@ -177,6 +177,11 @@ created_at: <now-datetime>
 ### 输出
 归档完成 + archive 目录路径`,
       outputHint: '归档确认',
+      // 坑 archive-batch-31-tool-notes ②：完成本步必须带 --confirm（complete-handlers 门控），
+      // 但 outputStep 机器生成的「完成后执行」提示原是通用 --done 模板不带 --confirm——agent
+      // 照抄执行就撞「请添加 --confirm」。requiresConfirm 让提示行带上该 flag（数据驱动，其他
+      // 阶段未来有确认步同样声明即可）。
+      requiresConfirm: true,
       optional: false
     },
     {

package/src/stages/execute.js

@@ -1064,7 +1064,7 @@ ${crossLines}${crossWorktreeSection}${crossLegacySection}
 
 **回收跨仓 task（head 锡点，CLI 自动落盘，勿手写）：**
 - 子代理完成 commit 后，正常写 review.json（verdict/notes）并勾选 checkbox 即可。execute \`--done\` 时 CLI 自动对跨仓仓（worktree 模式=该仓 worktree，legacy=仓根）\`git rev-parse HEAD\` 写入该 task 卡 \`head_commit:\`（幂等，已存在不覆盖——你若手写了精确锚点则以你的为准）。
-- review.json 的 mechanics 字段（\`base\`/\`head\`/\`changedFiles\`）无需手算：\`base\` 取 task 卡 \`base_commit\`、\`head\` 取 task 卡 \`head_commit\`，写完跑 \`sillyspec backfill-reviews --change <变更名> --adopt\` 一键代填（verdict 保留）。
+- review.json 的 mechanics 字段（\`base\`/\`head\`/\`changedFiles\`/\`diffPaths\`）无需手算：\`base\` 取 task 卡 \`base_commit\`、\`head\` 取 task 卡 \`head_commit\`，写完跑 \`sillyspec backfill-reviews --change <变更名> --adopt\` 一键代填（verdict 保留）。
 `
   }
 
@@ -1214,6 +1214,7 @@ ${taskList}
 4. 每个任务完成后：
    - **在 worktree 内 git add -A && git commit -m "<task-NN 摘要>"**（坑 subagent-uncommitted-newfile-apply3way，2026-08-22 实证：纯新增文件不 commit 时 apply 的 git apply --3way 报 "does not exist in index" 直接炸——未 commit 的新文件不在 base commit 也不在 index，patch 生成取不到。commit 后 base..HEAD diff 完整、apply 顺畅，review.json 的 head 也有真实锚点）
    - **先写 review.json 再勾选 checkbox**（见下方 Task Review Gate）
+   - **任务边界上报（每任务一次，主仓根目录）**：勾选 checkbox 后跑一次 \`sillyspec platform sync --change <change-name>\`——以任务粒度把「最后信号」（last_pushed_at）与 tasks.md 勾选状态推上平台（变更中心「进行中」可见性）；未连接平台时该命令静默跳过，无需先检查连接状态
    - **既跑 lint check 也跑 formatter**：凡变更涉及的源码跑项目的 lint 检查 **和** 格式化（如 \`ruff format\` / \`prettier --write\`），不要只跑 check——只 check 不 format 会把格式问题留到 commit 时被 pre-commit hook 拦截（worktree 内二进制可能缺失，先 \`which <bin>\` 确认，缺则 \`uv tool install\` / \`uv sync\`）
    - 记录改动文件和测试结果
 5. 遇到 BLOCKED → 记录原因，选择：重试/跳过/停止
@@ -1242,9 +1243,13 @@ task-XX 对应：{SPEC_ROOT}/.runtime/execute-runs/{EXECUTE_RUN_ID}/tasks/task-X
  "qualityVerdict": "pass|fail|cannot_verify", "reviewerNotes": "评审说明",
  "requiredEvidence": [] }
 
+**base/head 两种取法（按提交模式选其一）：**
+- **per-task commit 模式**（默认，子代理每 task 一提交）：base=本 task 开始前的 commit，head=本 task 的 commit——base..head 天然就是本 task 的 diff，无需 diffPaths。
+- **统一 commit 模式**（主代理统一实现/收尾一次性 commit，全部 task 一个提交）：base=基线 commit（worktree meta 的 baseHash），head=统一 commit，并**必填 \`diffPaths\`（本 task 卡的 allowed_paths 原样数组）**——评审与 CLI 校验的 diff 都是 \`git diff base..head -- diffPaths\` 的路径限定切片，任务边界由 diffPaths 机器可验，不再只靠 changedFiles 归属说明。changedFiles 填切片内实际改动的文件。
+
 **评审铁律：**
 - 不信任 implementer 自报结果，对照 diff 和 task brief 验证
-- 只看当前 task 的 diff，不做全仓库漫游审查
+- 只看当前 task 的 diff（统一 commit 模式=路径限定切片），不做全仓库漫游审查
 - \`cannot_verify\` 只在确实无法验证且有待补充证据时使用，且 requiredEvidence 必须非空
 - \`sillyspec run execute --done\` 会校验所有 task 的 review.json，缺失或 fail 会阻断完成