sillyspec 3.27.11 → 3.28.0

package/src/sync.js

@@ -8,13 +8,14 @@
  * HTTP 请求：Node.js 原生 fetch（Node 22+）
  */
 
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, unlinkSync, chmodSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, unlinkSync, chmodSync, rmSync } from 'fs';
+import { createHash } from 'crypto';
 import { writeAtomicSync } from './fs-atomic.js';
-import { join } from 'path';
+import { join, dirname, basename, isAbsolute, relative } from 'path';
 import { resolvePlatformSpecDir } from './progress.js';
 import { safeGit } from './git-helper.js';
 import { openDatabase } from './db-engine.js';
-import { PLATFORM_MANAGED_FILENAME } from './run/shared.js';
+import { PLATFORM_MANAGED_FILENAME, QUICK_SID_RE } from './run/shared.js';
 import { syncSpecTree } from './spec-sync.js';
 
 // sync 是 best-effort（网络失败只 warn）：平台指针失效时不抛，跳过平台、回退本地。
@@ -29,6 +30,9 @@ function safePlatformSpecDir(cwd) {
 
 const LOCAL_YAML = '.sillyspec/local.yaml';
 const REQUEST_TIMEOUT_MS = 10_000;
+// X2 spec bundle 整树下载（tar 流式响应体，审计 B2）：大树/慢网远超常规 JSON 轮询口径，
+// 独立大超时（daemon 同端点 30s；CLI 面向交互式大仓更宽）。
+const PULL_BUNDLE_TIMEOUT_MS = 120_000;
 
 // 未连接平台是本地独立用户的合法默认状态。sync / checkApproval 由 run 流程在后台 best-effort
 // 触发（每步完成、execute 阶段启动）；syncDocuments 仅由手动 `sillyspec platform sync-docs`
@@ -205,8 +209,10 @@ function resolvePlatformUser(cwd, explicitUser) {
 // HUB-09：单请求超时与外部 signal 合并——自动同步熔断（run/shared.js trigger* 的 race）
 // 触发 abort 时在飞 fetch 被真实取消，而不是熔断后任由请求自行完成（平台可能已接受，
 // 客户端却当作超时放弃；spec 树推送无 base_ts 自愈兜底）。AbortSignal.any 需 Node ≥20.3。
-function combineSignals(external) {
-  const timeoutSignal = AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+// timeoutMs 可选：pullSpecBundle 整树下载走 PULL_BUNDLE_TIMEOUT_MS 大口径（审计 B2），
+// 其余调用缺省 REQUEST_TIMEOUT_MS。
+function combineSignals(external, timeoutMs = REQUEST_TIMEOUT_MS) {
+  const timeoutSignal = AbortSignal.timeout(timeoutMs);
   return external ? AbortSignal.any([timeoutSignal, external]) : timeoutSignal;
 }
 
@@ -262,6 +268,129 @@ async function fetchJsonWithStatus(url, options = {}) {
   }
 }
 
+// ── X2 spec bundle tar 解析（task-14 / design §7.1）──
+
+// 平台 build_bundle（spec_workspace/service.py，Python tarfile mode "w"）输出未压缩 tar，
+// Python 3.8+ 默认 PAX 格式：路径 ≤100 字符是纯 ustar 头，超限走 typeflag 'x' 的 PAX
+// 扩展头（path 记录）+ 截断名条目；GNU tar 长名走 'L'。仓内无三方 tar 库（package.json
+// deps 无 tar/zlib 需求），按 512 字节头极简自实现——tar-slip 双重校验照搬 daemon
+// extractTar（sillyhub-daemon/src/spec-sync.ts:982）同款范式，两仓行为对齐。
+
+/** tar 头字符串字段读：截到首个 NUL，去首尾空白。 */
+function _readTarString(buf) {
+  const end = buf.indexOf(0);
+  const s = (end === -1 ? buf : buf.subarray(0, end)).toString('utf8');
+  return s.replace(/\0/g, '').trim();
+}
+
+/** tar 头 size 字段（12 字节八进制）→ 字节数。 */
+function _readTarSize(field) {
+  const s = _readTarString(field);
+  if (!s) return 0;
+  return parseInt(s, 8) || 0;
+}
+
+/**
+ * PAX 扩展头 data 解析为 {key: value}：记录形态 "<len> <key>=<value>\n" 重复，
+ * len 十进制**字节数**且含自身位数、空格与尾部 \n。
+ * 必须在 Buffer 上按字节偏移推进/切片：value 含非 ASCII（中文文件名）时 len（字节）
+ * > JS 字符串长度（UTF-16 码元），按码元校验会首记录即 break、path 丢失 → 文件落
+ * 实体头 name 的 ascii/replace 混淆路径并互相覆盖（与 daemon spec-sync.ts 同款修复）。
+ */
+function _parsePaxRecords(data) {
+  const out = {};
+  let pos = 0;
+  while (pos < data.length) {
+    const sp = data.indexOf(0x20, pos);
+    if (sp === -1) break;
+    const len = parseInt(data.toString('utf8', pos, sp), 10);
+    if (!Number.isInteger(len) || len <= 0 || pos + len > data.length) break;
+    const record = data.toString('utf8', sp + 1, pos + len - 1); // 尾部 \n 不属于 value
+    const eq = record.indexOf('=');
+    if (eq > 0) out[record.slice(0, eq)] = record.slice(eq + 1);
+    pos += len;
+  }
+  return out;
+}
+
+/**
+ * tar-slip 双重校验（daemon extractTar 同款）：显式穿越模式 + join 后 relative 复核。
+ * 通过返回安全相对路径的原样 name；命中穿越抛 Error（调用方转为失败 reason，不落盘）。
+ */
+function _assertSafeTarName(name, targetDir) {
+  if (name.includes('..') || isAbsolute(name) || /^[A-Za-z]:[\\/]/.test(name)) {
+    throw new Error(`tar 路径越界已拦截: ${name}`);
+  }
+  const fullPath = join(targetDir, name);
+  const rel = relative(targetDir, fullPath);
+  if (rel.startsWith('..') || isAbsolute(rel)) {
+    throw new Error(`tar 路径逃逸目标目录已拦截: ${name} -> ${fullPath}`);
+  }
+}
+
+/**
+ * 解析整只未压缩 tar 为条目列表 [{ name, isDir, data }]（先全量解析校验，后落盘——
+ * 恶意/损坏 tar 在任何本地删除动作之前暴露，见 pullSpecBundle 覆盖顺序）。
+ * 容忍并落地 tar 顶层 PLATFORM-BUNDLE.json（task-08 快照元数据，design §7.3）；
+ * symlink/fifo/dev 等非常规条目跳过（spec 树不应含，daemon 同款）。
+ * @param {Buffer} tarBuf
+ * @returns {Array<{name: string, isDir: boolean, data: Buffer}>}
+ */
+function _parseSpecTar(tarBuf) {
+  const entries = [];
+  let offset = 0;
+  let pendingPath = null; // PAX 'x' path 记录 / GNU 'L' 长名，覆盖下一实条目的 name
+  while (offset + 512 <= tarBuf.length) {
+    const header = tarBuf.subarray(offset, offset + 512);
+    if (header.every((b) => b === 0)) break; // 结尾 zero block → 结束
+    const typeflag = String.fromCharCode(header[156] ?? 0);
+    const size = _readTarSize(header.subarray(124, 136));
+    offset += 512;
+    const data = tarBuf.subarray(offset, offset + size);
+    offset += Math.ceil(size / 512) * 512;
+
+    let name = _readTarString(header.subarray(0, 100));
+    // POSIX ustar prefix 字段（magic 'ustar\0' + version '00' 时有效）；GNU 长名走 'L' 条目
+    const magic = header.subarray(257, 263).toString('latin1');
+    const version = header.subarray(263, 265).toString('latin1');
+    if (magic.startsWith('ustar') && version === '00') {
+      const prefix = _readTarString(header.subarray(345, 500));
+      if (prefix) name = `${prefix}/${name}`;
+    }
+    if (pendingPath) { name = pendingPath; pendingPath = null; }
+
+    if (typeflag === 'x' || typeflag === 'X') {
+      const recs = _parsePaxRecords(data);
+      if (recs.path) pendingPath = recs.path;
+      continue;
+    }
+    if (typeflag === 'L') { // GNU LongLink（长文件名）
+      pendingPath = _readTarString(data);
+      continue;
+    }
+    if (typeflag === 'K') continue; // GNU 长链接目标：spec 树无符号链接，跳过
+    if (!name) continue;
+
+    if (typeflag === '5' || name.endsWith('/')) {
+      _assertSafeTarName(name.replace(/\/+$/, ''), '.'); // 目录条目同样过穿越校验（相对假根）
+      entries.push({ name, isDir: true, data: Buffer.alloc(0) });
+      continue;
+    }
+    if (typeflag === '0' || typeflag === '\0') {
+      _assertSafeTarName(name, '.');
+      entries.push({ name, isDir: false, data });
+      continue;
+    }
+    debugLog(`[sync] spec bundle tar 跳过非常规条目: ${name} (typeflag ${typeflag})`);
+  }
+  return entries;
+}
+
+/** 目录有内容判定（daemon dirHasContent 同语义）：不存在/读失败/空均视为无内容。 */
+function _dirHasContent(dir) {
+  try { return readdirSync(dir).length > 0; } catch { return false }
+}
+
 // ── SyncManager ──
 
 export class SyncManager {
@@ -438,18 +567,29 @@ export class SyncManager {
     const changeDir = join(specBase, 'changes', changeName);
     let archivedQuietly = false;
     if (!existsSync(changeDir)) {
-      archivedQuietly = existsSync(join(specBase, 'changes', 'archive', changeName))
-        || this._isChangeArchivedInDb(changeName);
-      if (archivedQuietly) {
-        console.log(`[sync] 变更已归档（目录在 archive/），继续从 DB 推送最终状态: ${changeName}`);
+      // change-delete（2026-08-30）：DB status='deleted' 的行目录已随删除移除，属正常时序，
+      // 单行 info 提示后继续推删除终态/墓碑（不落入「目录不存在」warn）
+      if (this._changeDbStatus(changeName) === 'deleted') {
+        console.log(`[sync] 变更已删除（DB status=deleted），继续推送删除终态/墓碑: ${changeName}`);
       } else {
-        console.warn(`[sync] 变更目录不存在（可能是已归档，继续从 DB 同步最终状态）: ${changeName}`);
+        archivedQuietly = existsSync(join(specBase, 'changes', 'archive', changeName))
+          || this._changeDbStatus(changeName) === 'archived';
+        if (archivedQuietly) {
+          console.log(`[sync] 变更已归档（目录在 archive/），继续从 DB 推送最终状态: ${changeName}`);
+        } else {
+          console.warn(`[sync] 变更目录不存在（可能是已归档，继续从 DB 同步最终状态）: ${changeName}`);
+        }
       }
     }
     // 透传给本次 sync 链内的 syncDocuments（best-effort 四件套直推：归档后目录已移走，
     // 其「变更不存在」warn 属正常时序，静默化）
     this._suppressDocsMissingWarn = archivedQuietly;
 
+    // X1 墓碑（design §5.5，变更 2026-08-29-change-delete-closure-and-spec-pull task-13）：
+    // 触发判据见循环内 tombstoneDue（DB status='archived'）。
+    // 常规终态推送保持原语义（archived/active 原值照推，platform-sync-archive-final-state 钉死），
+    // 墓碑作为推送链成功后的追加 POST（见 _pushTombstone）。
+
     const MAX_PUSH_ATTEMPTS = 2;
     for (let attempt = 1; attempt <= MAX_PUSH_ATTEMPTS; attempt++) {
       // 读取 progress 数据（serializeForSync 六表裸 JSON，task-02 / D-005@v2，替代 read() 聚合视图）。
@@ -468,6 +608,25 @@ export class SyncManager {
         return { synced: 0, errors: [`变更无进度数据: ${changeName}`] };
       }
 
+      // X1 墓碑判定（design §5.5 / task-13；审计 B1 收窄）：仅 DB status='archived'
+      // （unregisterChange 链——归档收尾/自愈/quick 收尾均置该值）或 status='deleted'
+      // （change-delete 命令，2026-08-30——载荷本身携带 deleted，平台 _apply_cli_tombstone
+      // 见该值即置 location='deleted'；追加墓碑 POST 幂等兜底）触发，常规推送成功后追加
+      // 一次 changes[].status='deleted' 墓碑（平台 task-04 写路径置 location='deleted' 收敛镜像）。
+      // 不再把「实体目录双失」当裸删发墓碑：platform pull（进度同步）只写 DB 不建目录 →
+      // DB active + 目录双失是合法态，误发墓碑会让平台把活跃变更软删（全体成员生效）。
+      // 真实裸删（用户手动 rm -rf 目录）由平台镜像收敛兜底（spec-sync delete ops → scoped
+      // 定向删除，computeSpecOps 护栏只拦整树/changes 整删，不拦单变更 scoped 删除），
+      // CLI 不发墓碑不损失收敛。quick 会话豁免：triggerSync 对 quick 已降级 syncSpecTreeOnly，
+      // 直调也不给孤儿 key 造墓碑。
+      const tombstoneDue = !QUICK_SID_RE.test(changeName)
+        && (progressData.changes?.[0]?.status === 'archived'
+          || progressData.changes?.[0]?.status === 'deleted');
+
+      // X3 步骤开始上报（design §8.2 / task-13）：opts.stepStart 时把 current_stage 的第一个
+      // 未完成步投影为 in-progress（仅载荷不写 DB；triggerStepStartSync 是唯一传该 flag 的入口）
+      if (opts.stepStart) this._projectStepStart(progressData, changeName);
+
       // 元字段走 HTTP header（D-015 / task-09）：body 保持裸六表 JSON，sillyhub 老版忽略 header 零回归
       const headers = {
         'Content-Type': 'application/json',
@@ -493,6 +652,14 @@ export class SyncManager {
         signal: opts.signal, // HUB-09：熔断 abort 传到底层请求
       });
 
+      // X1（task-04 契约）：409 + code='change_deleted' = 平台已删 key 拒收——不是 base_ts 冲突。
+      // 单行提示即可，不落冲突文件、不打全幅横幅：墓碑已收敛后的重复上行（归档收尾多步各推一次）、
+      // 多用户下他端删除后本地仍在推进，都是可预期态，按冲突卡死人工 resolve 反而是误报。
+      if (res.status === 409 && res.body && res.body.code === 'change_deleted') {
+        console.warn(`⚠️ [sync] 平台已删除变更「${changeName}」，本次进度上行被拒收（change_deleted）；本地如仍需推进请在平台侧确认`);
+        return { synced: 0, errors: [], platformDeleted: true, reason: '平台已删除（change_deleted 拒收）' };
+      }
+
       if (res.ok) {
         // 更新 platform_last_sync + 推进 base_ts（ql-20260818-008：值优先平台回执 last_pushed_at，
         // 缺省用本次 pushedAt——服务器 _apply 存的就是客户端 X-SillySpec-Pushed-At 原值，回写一致。
@@ -541,6 +708,18 @@ export class SyncManager {
           debugLog(`[sync] spec 树增量同步失败（不影响进度）: ${changeName}: ${err.message}`);
         }
 
+        // X1 墓碑上行（收敛加速器，best-effort）：常规终态 + 文档/spec 树都推完后追加一次
+        // changes[].status='deleted'（顺序在后——常规推送保持 archived/active 原语义是既有
+        // 契约，platform-sync-archive-final-state 钉死）。失败静默：平台闭环走方案 A 镜像驱动
+        // 收敛（design §5.5），墓碑只是让收敛即时。
+        if (tombstoneDue) {
+          try {
+            await this._pushTombstone(changeName, { signal: opts.signal });
+          } catch (err) {
+            debugLog(`[sync] 墓碑上行失败（不影响主推送）: ${changeName}: ${err.message}`);
+          }
+        }
+
         return { synced: 1, errors: [] };
       }
 
@@ -620,6 +799,92 @@ export class SyncManager {
     return { synced: 0, errors: [`同步重试耗尽（仍冲突）: ${changeName}`] };
   }
 
+  /**
+   * X3 步骤开始上报的载荷投影（design §8.2，变更 2026-08-29-change-delete-closure-and-spec-pull
+   * task-13）：把 current_stage 下第一个未完成步（completed/skipped 之外，含 waiting——等待中
+   * 的步同样「在跑」）的 status 改为 'in-progress'。
+   *
+   * 仅改本次上行载荷，不写 DB——步骤行 DB 种子是 pending，completeStep 的
+   * findIndex(pending||in-progress) 两者等价，但保持 DB 不被推送侧污染（--done 推送路径
+   * 行为不变，回归约束）。六表 steps[].status 状态机本就含 in-progress 值（step-store
+   * VALID_STATUSES），平台侧裸 JSON 透传（design §8.2 已核实后端零改动）。
+   * @param {object} progressData serializeForSync 输出（原地修改）
+   * @param {string} changeName
+   */
+  _projectStepStart(progressData, changeName) {
+    try {
+      const row = progressData && progressData.changes && progressData.changes[0];
+      if (!row || !row.current_stage || !Array.isArray(progressData.steps)) return;
+      const idx = progressData.steps.findIndex(s =>
+        s.change_name === changeName && s.stage === row.current_stage
+        && s.status !== 'completed' && s.status !== 'skipped');
+      if (idx !== -1) progressData.steps[idx].status = 'in-progress';
+    } catch { /* 投影失败按原载荷推送（best-effort） */ }
+  }
+
+  /**
+   * X1：把墓碑状态写进载荷——changes[0].status='deleted'（对齐既有 'archived' 状态语义，
+   * design §5.5）。平台写路径（服务端 task-04 `_apply_cli_tombstone`）见到该值即置
+   * Change.location='deleted' 并触发镜像软删收敛。
+   * @param {object} progressData serializeForSync 输出（原地修改，返回同一引用）
+   */
+  _applyTombstoneStatus(progressData) {
+    if (progressData && Array.isArray(progressData.changes) && progressData.changes[0]) {
+      progressData.changes[0].status = 'deleted';
+    }
+    return progressData;
+  }
+
+  /**
+   * X1 墓碑上行（design §5.5 / task-13）：同端点同结构的一次追加 POST（changes[].status='deleted'）。
+   *
+   * 由 sync() 成功路径在常规推送 + 文档/spec 树链之后触发（CLI 单进程顺序推送，base_ts 进程内
+   * 单调，无乐观锁冲突）。fresh 重读 DB 序列化——常规推送成功的 base_ts 回填已落库，本推送带上
+   * 该 base_ts；重复墓碑（平台已删）收到 409 code='change_deleted' 属预期，静默返回。
+   * Best-effort：任何失败只 debugLog，不影响 sync() 主结果（平台闭环走方案 A 兜底）。
+   * @param {string} changeName
+   * @param {{signal?: object}} [opts]
+   * @returns {Promise<{synced: number}>}
+   */
+  async _pushTombstone(changeName, opts = {}) {
+    const platform = this._getPlatform();
+    if (!platform) return { synced: 0 };
+    const { ProgressManager } = await import('./progress.js');
+    const pm = new ProgressManager({ specDir: safePlatformSpecDir(this.cwd) });
+    const progressData = pm.serializeForSync(this.cwd, changeName);
+    if (progressData === null) return { synced: 0 }; // DB 行已不在（彻底删除），无墓碑可推，方案 A 兜底
+    this._applyTombstoneStatus(progressData);
+
+    const headers = {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${platform.token}`,
+    };
+    const pushedAt = new Date().toISOString();
+    const pushUser = platform.user || resolvePlatformUser(this.cwd) || null;
+    if (pushUser) headers['X-SillySpec-User'] = pushUser;
+    const baseTs = progressData.changes?.[0]?.last_synced_platform_ts;
+    if (baseTs) headers['X-SillySpec-Base-Ts'] = baseTs;
+    headers['X-SillySpec-Pushed-At'] = pushedAt;
+
+    const syncUrl = `${platform.url}/api/changes/${encodeURIComponent(changeName)}/progress`;
+    const res = await fetchJsonWithStatus(syncUrl, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(progressData),
+      signal: opts.signal,
+    });
+    if (res.ok) {
+      console.log(`[sync] 已上行墓碑（status=deleted）: ${changeName}`);
+      try {
+        const ackTs = res.body && typeof res.body.last_pushed_at === 'string' ? res.body.last_pushed_at : pushedAt;
+        pm._updatePlatformLastSync(this.cwd, changeName, ackTs);
+      } catch { /* 回填失败下次 push 409 由自竞态自愈收敛 */ }
+      return { synced: 1 };
+    }
+    debugLog(`[sync] 墓碑上行未成功: ${changeName} (status=${res.status}，平台方案 A 兜底)`);
+    return { synced: 0 };
+  }
+
   /**
    * 自竞态判定辅助：fresh 读本地 DB 的 last_synced_platform_ts（base_ts），判断它是否已覆盖
    * 平台 409 回执的 last_pushed_at（字符串字典序比较，契约 §4.2——ISO 8601 字典序 == 时间序）。
@@ -806,22 +1071,23 @@ export class SyncManager {
   }
 
   /**
-   * DB 侧归档态探测（坑 post-archive-sync-noise）：changes 表 status='archived' 即真。
+   * DB 侧变更状态探测（坑 post-archive-sync-noise；2026-08-30 泛化）：只读直查 changes.status，
+   * 供「目录缺失」降噪分支区分 archived（归档终态照推）与 deleted（change-delete 删除终态）。
    * 只读直查（node:sqlite，不经 ProgressManager——sync 是短进程，惰性 import 无收益且
-   * 本调用点在同步代码段）；DB 不存在/无行/读失败 → false（保守退回普通 warn 措辞）。
+   * 本调用点在同步代码段）；DB 不存在/无行/读失败 → null（保守退回普通 warn 措辞）。
    * @param {string} changeName
-   * @returns {boolean}
+   * @returns {string|null}
    */
-  _isChangeArchivedInDb(changeName) {
+  _changeDbStatus(changeName) {
     try {
       const dbPath = join(safePlatformSpecDir(this.cwd) || join(this.cwd, '.sillyspec'), '.runtime', 'sillyspec.db');
-      if (!existsSync(dbPath)) return false;
+      if (!existsSync(dbPath)) return null;
       const db = openDatabase(dbPath, { readOnly: true });
       try {
         const row = db.prepare("SELECT status FROM changes WHERE name = ?").get(changeName);
-        return row?.status === 'archived';
+        return row?.status || null;
       } finally { try { db.close() } catch {} }
-    } catch { return false }
+    } catch { return null }
   }
 
   /**
@@ -1115,6 +1381,262 @@ export class SyncManager {
     }
   }
 
+  /**
+   * X2（task-14 / design §7.1 / FR-07 / FR-08）：拉平台 spec 整树快照并解压到 specDir。
+   *
+   * 与既有 pull()（进度六表 DB import）正交：本方法操作的是 .sillyspec **文件树**——
+   * GET {platform.url}/api/changes/-/spec-bundle（task-08 端点，Bearer shpsync token，
+   * application/x-tar 流 + X-Spec-Version 响应头）下载未压缩 tar 后解包。
+   *
+   * 覆盖语义对齐 daemon pullSpecBundle（sillyhub-daemon/src/spec-sync.ts）：
+   * - specDir 为空（或不存在）→ 直接解压；
+   * - 非空且无 force → 拒绝并明确提示（fail-fast，不发网络请求）；
+   * - force → rm 整树 + 解包（先下载并全量解析校验 tar，成功后才 rm——恶意/损坏
+   *   bundle 不先删本地）。local.yaml 是唯一保留例外：本机连接凭据，服务端 bundle
+   *   恒排除它（spec-sync.js UPLOAD_EXCLUDE_FILENAMES），rm 前读出、解包落定后
+   *   原样恢复——删它零收益纯断连。崩溃安全（审计 B3）：rm 前凭据先原子备份到树外
+   *   `<specDir 根名>.local.yaml.bak`，成功后自动清理；恢复失败时从 .bak 兜底复制，
+   *   兜底也失败则 .bak 留在现场供手工恢复（凭据不因覆盖中断永久丢失）。
+   *
+   * 快照语义（design §7.4）：主动拉取服务器**打包时刻**快照，无自动同步、无会话中
+   * 刷新；daemon 模式任务/会话开始时按 latest_spec_version 自动取新（本方法不涉）。
+   *
+   * Best Effort：未连接平台静默跳过（本地合法状态）；网络/解包失败返回 ok:false 不抛。
+   * @param {{force?: boolean, specDir?: string|null, signal?: AbortSignal}} [opts]
+   *   force 整树覆盖；specDir 显式覆盖树根（--spec-dir 全局选项通道；缺省与 sync()
+   *   同源：平台模式锚 specRoot，本地模式 cwd/.sillyspec）；signal 外部熔断
+   * @returns {Promise<{ok: boolean, pulled: boolean, specDir?: string, specVersion?: string|null, reason?: string}>}
+   */
+  async pullSpecBundle(opts = {}) {
+    const { force = false } = opts;
+    const platform = this._getPlatform();
+    if (!platform) {
+      debugLog('[sync] 未连接平台（本地合法状态）；pullSpecBundle 跳过');
+      return { ok: false, pulled: false, reason: '未连接平台' };
+    }
+    // 树根与 sync()/spec 树推送同源（BUG-01：平台模式必须锚 specRoot，勿硬编码 cwd/.sillyspec）
+    const specDir = opts.specDir || safePlatformSpecDir(this.cwd) || join(this.cwd, '.sillyspec');
+
+    // 覆盖守卫（daemon 同款）：非空且无 --force 拒绝——先于网络请求，本地不可逆动作前 fail-fast
+    if (_dirHasContent(specDir) && !force) {
+      return {
+        ok: false, pulled: false, specDir,
+        reason: `specDir 非空（${specDir}），拒绝整树覆盖；确认用平台快照替换本地请加 --force`,
+      };
+    }
+
+    // 下载流式 tar（spec 树小，整只缓冲与 daemon getSpecBundle 同口径）。
+    // 审计 B2：下载（含响应体读取）走 PULL_BUNDLE_TIMEOUT_MS 独立大口径——大树/慢网下
+    // 10s 常规轮询口径必超时；仍尊重外部熔断 signal（两者 combine）。
+    const bundleUrl = `${platform.url}/api/changes/-/spec-bundle`;
+    let res;
+    try {
+      res = await fetch(bundleUrl, {
+        headers: { Authorization: `Bearer ${platform.token}` },
+        signal: combineSignals(opts.signal, PULL_BUNDLE_TIMEOUT_MS),
+      });
+    } catch (err) {
+      // AbortSignal.timeout 到期抛 TimeoutError，外部 signal abort 抛 AbortError，两者都是超时/中断口径
+      const why = (err.name === 'AbortError' || err.name === 'TimeoutError')
+        ? `下载超时/中断 (${PULL_BUNDLE_TIMEOUT_MS / 1000}s 上限或外部熔断)`
+        : err.message;
+      console.warn(`[sync] GET ${bundleUrl} 请求失败: ${why}`);
+      return { ok: false, pulled: false, specDir, reason: `拉取 spec bundle 失败: ${why}` };
+    }
+    if (!res.ok) {
+      const why = res.status === 404
+        ? '平台工作区尚无 spec 内容（HTTP 404，空 bundle）'
+        : `HTTP ${res.status}`;
+      console.warn(`[sync] GET ${bundleUrl} → ${res.status}`);
+      return { ok: false, pulled: false, specDir, reason: `拉取 spec bundle 失败: ${why}` };
+    }
+    const specVersion = res.headers.get('x-spec-version');
+    let tarBuf;
+    try {
+      tarBuf = Buffer.from(await res.arrayBuffer());
+    } catch (err) {
+      console.warn(`[sync] 读取 spec bundle 响应体失败: ${err.message}`);
+      return { ok: false, pulled: false, specDir, reason: `读取 spec bundle 失败: ${err.message}` };
+    }
+
+    // 全量解析 + 穿越校验在 rm 之前（tar-slip 命中时本地原样保留）
+    let entries;
+    try {
+      entries = _parseSpecTar(tarBuf);
+    } catch (err) {
+      console.warn(`[sync] spec bundle 无效: ${err.message}`);
+      return { ok: false, pulled: false, specDir, reason: `spec bundle 无效: ${err.message}` };
+    }
+
+    // 覆盖语义：rm 整树（容忍不存在）→ 逐条目落盘（join 后 relative 双重校验再走一道）
+    // local.yaml 唯一豁免（rm 前校验存在性并读出，解包落定后原样恢复 + 校验回存在）：
+    // 本机连接凭据（platform/mcp 段含 shpsync token），服务端 bundle 恒排除它
+    // （spec-sync.js UPLOAD_EXCLUDE_FILENAMES）——rm 整树删它零收益纯断连。恢复放在
+    // 条目循环之后，即便异常 bundle 携带同名条目也以本地为准（凭据永不取自服务端）。
+    //
+    // 审计 B3 崩溃安全（三层）：rm 整树后凭据只剩内存 Buffer，任一步失败（条目写失败/
+    // 恢复写失败——Windows EPERM·AV 锁·磁盘满）或进程崩溃即凭据永久丢失。三层防护：
+    // ①rm 前先把内容原子写到树外 `<specDir 根名>.local.yaml.bak`（树内会被 rm 一并删掉，
+    //   故放父目录）；②恢复主路径不变，失败时从 .bak 再兜底复制一次；③成功路径末尾
+    //   清理 .bak（明文 token 不留第二份；顺带清历史失败残留）。
+    const localYamlPath = join(specDir, 'local.yaml');
+    const localYamlBakPath = join(dirname(specDir), `${basename(specDir)}.local.yaml.bak`);
+    let localYamlSaved = null; // null = 本无此文件，无需恢复
+    if (existsSync(localYamlPath)) {
+      try {
+        localYamlSaved = readFileSync(localYamlPath); // Buffer 字节级：注释/CRLF 原样
+      } catch (err) {
+        // fail-closed：读不出就无从恢复，继续 rm = 确定性丢凭据断连，宁可整单拒绝
+        console.warn(`[sync] local.yaml 存在但读取失败，拒绝 --force 整树覆盖: ${err.message}`);
+        return { ok: false, pulled: false, specDir, reason: `local.yaml 读取失败，已拒绝整树覆盖（防丢连接凭据）: ${err.message}` };
+      }
+      try {
+        writeAtomicSync(localYamlBakPath, localYamlSaved);
+        try { chmodSync(localYamlBakPath, 0o600); } catch { /* best-effort，同 local.yaml SEC-04 */ }
+      } catch (err) {
+        // 兜底都写不进（磁盘满等）：继续 rm = 凭据只剩内存一份，恢复再失败即永久丢失，拒绝整单
+        console.warn(`[sync] local.yaml 备份写入失败，拒绝 --force 整树覆盖: ${err.message}`);
+        return { ok: false, pulled: false, specDir, reason: `local.yaml 备份失败，已拒绝整树覆盖（防丢连接凭据）: ${err.message}` };
+      }
+    }
+    try {
+      rmSync(specDir, { recursive: true, force: true });
+    } catch (err) {
+      // Windows EPERM/EBUSY：整树内 .runtime/sillyspec.db 被运行中 daemon/CLI 持有时 rm 必失败
+      //（本地树未被删除，可安全整单退出；.bak 留待下次成功覆盖时清理）
+      const holdHint = err.code === 'EBUSY' || err.code === 'EPERM'
+        ? '（可能被运行中的 daemon/CLI 持有 .runtime/sillyspec.db，请先停止相关进程再 --force）' : '';
+      console.warn(`[sync] 删除本地 specDir 失败${holdHint}: ${err.message}`);
+      return { ok: false, pulled: false, specDir, reason: `删除本地 specDir 失败${holdHint}: ${err.message}` };
+    }
+    try {
+      for (const e of entries) {
+        _assertSafeTarName(e.name.replace(/\/+$/, ''), specDir);
+        const fullPath = join(specDir, e.name);
+        if (e.isDir) {
+          mkdirSync(fullPath, { recursive: true });
+        } else {
+          mkdirSync(dirname(fullPath), { recursive: true });
+          writeFileSync(fullPath, e.data);
+        }
+      }
+      if (localYamlSaved !== null) {
+        mkdirSync(specDir, { recursive: true }); // 空 bundle（零条目）时树根未被条目重建
+        writeAtomicSync(localYamlPath, localYamlSaved); // fs-atomic 契约：hook/probe 并发读 local.yaml
+        try { chmodSync(localYamlPath, 0o600); } catch { /* SEC-04 best-effort，同 writeLocalYamlRaw */ }
+        if (!existsSync(localYamlPath)) throw new Error('local.yaml 恢复后校验缺失');
+      }
+      // ③ 成功路径：兜底使命完成，清理 .bak（force:true 容忍本就无 .bak 的路径）
+      rmSync(localYamlBakPath, { force: true });
+    } catch (err) {
+      // ② 恢复兜底：主路径失败（条目写失败中断恢复 / 恢复自身失败）时从 .bak 再试一次，
+      // 仍失败不掩盖——.bak 留在树外原处，用户可手工复制为 local.yaml（凭据不因本次失败丢失）
+      if (localYamlSaved !== null && existsSync(localYamlBakPath)) {
+        try {
+          mkdirSync(specDir, { recursive: true });
+          writeAtomicSync(localYamlPath, readFileSync(localYamlBakPath));
+          try { chmodSync(localYamlPath, 0o600); } catch { /* best-effort */ }
+        } catch { /* .bak 兜底也失败：保留 .bak 现场供手工恢复 */ }
+        console.warn(`[sync] 连接凭据已备份于 ${localYamlBakPath}，恢复失败可手工复制为 local.yaml`);
+      }
+      console.warn(`[sync] 解压 spec bundle 失败: ${err.message}`);
+      return { ok: false, pulled: false, specDir, reason: `解压 spec bundle 失败: ${err.message}` };
+    }
+    console.log(`[sync] 已拉取 spec 快照并解压到 ${specDir}${specVersion ? `（平台 spec_version: ${specVersion}，打包时刻快照非实时）` : ''}`);
+    return { ok: true, pulled: true, specDir, specVersion };
+  }
+
+  /**
+   * spec 树 take-platform 落地（坑 spec-sync-conflict-no-take-platform，2026-09-03 用户实证
+   * 「冲突没有接受服务器版本选项」）：拉平台整树 bundle（GET /changes/-/spec-bundle，与
+   * pullSpecBundle 同端点同鉴权），但**只覆盖冲突文件列出的路径**——不整树替换，本会话/
+   * 他端的其他本地改动不动。服务器已无该路径（远端删除）→ 删本地对应文件。
+   *
+   * 覆盖后同步刷新内容基线快照（spec-sync-base.json）中被覆盖路径的 hash：下次
+   * syncSpecTree 的 dropFollowServerUpdates 判「本地未改动」不再回推——take-platform =
+   * 服务器胜出，本地内容即服务器内容，回推同值无害但走基线豁免更干净。
+   *
+   * fail-closed：路径越界（../、绝对路径）逐条跳过计入 skipped 不中断其余；bundle 拉取/
+   * 解析失败整体 ok:false（本地不动）。
+   * @param {string} specDir spec 树根
+   * @param {string[]} paths 冲突路径（POSIX 相对 specDir，来自冲突文件 conflicting_paths）
+   * @returns {Promise<{ok: boolean, overwritten?: number, removed?: number, skipped?: string[], reason?: string}>}
+   */
+  async _takePlatformSpecPaths(specDir, paths) {
+    const platform = this._getPlatform();
+    if (!platform) return { ok: false, reason: '未连接平台（take-platform 需拉平台 bundle）' };
+    if (!Array.isArray(paths) || paths.length === 0) return { ok: false, reason: '冲突文件缺 conflicting_paths，无可接受路径' };
+
+    const bundleUrl = `${platform.url}/api/changes/-/spec-bundle`;
+    let res;
+    try {
+      res = await fetch(bundleUrl, {
+        headers: { Authorization: `Bearer ${platform.token}` },
+        // 大树/慢网同 pullSpecBundle 口径（审计 B2），不与外部熔断组合（resolve 是用户显式动作）
+        signal: AbortSignal.timeout(PULL_BUNDLE_TIMEOUT_MS),
+      });
+    } catch (err) {
+      const why = (err.name === 'AbortError' || err.name === 'TimeoutError') ? `下载超时/中断（${PULL_BUNDLE_TIMEOUT_MS / 1000}s 上限）` : err.message;
+      return { ok: false, reason: `拉取 spec bundle 失败: ${why}` };
+    }
+    if (!res.ok) {
+      const why = res.status === 404 ? '平台工作区尚无 spec 内容（HTTP 404）' : `HTTP ${res.status}`;
+      return { ok: false, reason: `拉取 spec bundle 失败: ${why}` };
+    }
+    let tarBuf;
+    try { tarBuf = Buffer.from(await res.arrayBuffer()); }
+    catch (err) { return { ok: false, reason: `读取 spec bundle 失败: ${err.message}` }; }
+    let entries;
+    try { entries = _parseSpecTar(tarBuf); }
+    catch (err) { return { ok: false, reason: `spec bundle 无效: ${err.message}` }; }
+
+    const serverFiles = new Map();
+    for (const e of entries) {
+      if (e.isDir || e.name === 'PLATFORM-BUNDLE.json') continue;
+      serverFiles.set(e.name.replace(/^\.\//, ''), e.data);
+    }
+
+    const normalized = [...new Set(paths.map((p) => String(p).replace(/\\/g, '/')).filter(Boolean))];
+    let overwritten = 0;
+    let removed = 0;
+    const skipped = [];
+    for (const p of normalized) {
+      try {
+        _assertSafeTarName(p, specDir);
+        const data = serverFiles.get(p);
+        if (data !== undefined) {
+          const full = join(specDir, p);
+          mkdirSync(dirname(full), { recursive: true });
+          writeFileSync(full, data);
+          overwritten++;
+        } else if (existsSync(join(specDir, p))) {
+          // 服务器已无该文件（远端删除）→ 接受服务器 = 删本地
+          rmSync(join(specDir, p), { force: true });
+          removed++;
+        }
+      } catch {
+        skipped.push(p);
+      }
+    }
+
+    // 基线快照刷新（best-effort）：被覆盖路径回写当前盘面 hash（= 服务器内容 hash）、被删
+    // 路径移除条目——下次同步这些路径按「本地未改动」豁免回推（take-platform 语义闭环）。
+    try {
+      const baseFile = join(specDir, '.runtime', 'spec-sync-base.json');
+      let base = null;
+      try { base = JSON.parse(readFileSync(baseFile, 'utf8')); } catch { base = null; }
+      const hashes = base && typeof base.hashes === 'object' ? base.hashes : {};
+      for (const p of normalized) {
+        try { hashes[p] = createHash('sha256').update(readFileSync(join(specDir, p))).digest('hex'); }
+        catch { delete hashes[p]; }
+      }
+      mkdirSync(join(specDir, '.runtime'), { recursive: true });
+      writeFileSync(baseFile, JSON.stringify({ ts: Date.now(), hashes }, null, 2) + '\n', 'utf8');
+    } catch { /* 快照失败只损失下次的防回推精度，覆盖结果本身已成立 */ }
+
+    return { ok: true, overwritten, removed, skipped };
+  }
+
   /**
    * 冲突解决三选一（task-13 / D-002 / D-010 / D-013 / FR-05）。
    * 读 task-12 写的 sync-conflict-<change>.json，按 mode 处理后必清冲突文件防累积（R-04 / constraints）。
@@ -1206,9 +1728,11 @@ export class SyncManager {
     let specOutcome = null;
     if (specCf && mode === 'keep-local') {
       // keep-local = 本地胜出：重新 GET 清单重定 base 后 POST 本地内容（last-writer-wins），
-      // 成功清冲突文件闭环；仍冲突（平台又有更新）保留文件待下次裁决
+      // 成功清冲突文件闭环；仍冲突（平台又有更新）保留文件待下次裁决。
+      // forcePush（坑 quicksync-conflict-granularity）：用户显式裁决后本地意志高于
+      // 「未改动跟随服务器」语义——强制重推不得被内容基线/mtime 防回推过滤削掉。
       try {
-        const r = await syncSpecTree(safePlatformSpecDir(this.cwd) || join(this.cwd, '.sillyspec'), this._getPlatform(), changeName);
+        const r = await syncSpecTree(safePlatformSpecDir(this.cwd) || join(this.cwd, '.sillyspec'), this._getPlatform(), changeName, { forcePush: true });
         if (!r.conflict) {
           this.clearSpecConflictFile(changeName);
           specOutcome = { ok: true, resolved: true, reason: 'spec 树已以本地为准重定基线重推，冲突闭环' };
@@ -1219,8 +1743,32 @@ export class SyncManager {
         specOutcome = { ok: false, resolved: false, reason: `spec 树重推异常: ${err.message}` };
       }
     } else if (specCf && mode === 'take-platform') {
-      // fail-closed：平台无文件下载端点，无法把服务器内容写回本地——明确报错指路，不清文件
-      specOutcome = { ok: false, resolved: false, reason: 'spec 树冲突不支持 take-platform（平台无文件下载端点，无法把服务器内容写回本地）：请手动对齐本地文件后跑 --keep-local' };
+      // spec 树 take-platform（坑 spec-sync-conflict-no-take-platform，2026-09-03 用户实证反馈
+      // 「冲突没有接受服务器版本选项」）：平台已有 CLI 可用的整树下载端点（GET /changes/-/
+      // spec-bundle，X2 task-08）——拉 bundle 只覆盖冲突文件列出的路径（不整树替换，本地其他
+      // 改动不动），基线快照同步刷新防回推，清冲突文件闭环。此前 fail-closed 报「平台无文件
+      // 下载端点」是端点落地前的旧事实。
+      try {
+        const specDir = safePlatformSpecDir(this.cwd) || join(this.cwd, '.sillyspec');
+        const paths = Array.isArray(specCf.conflicting_paths) && specCf.conflicting_paths.length > 0
+          ? specCf.conflicting_paths
+          : Object.keys(specCf.server_versions || {});
+        const r = await this._takePlatformSpecPaths(specDir, paths);
+        if (r.ok) {
+          this.clearSpecConflictFile(changeName);
+          const skippedNote = r.skipped && r.skipped.length > 0
+            ? `，${r.skipped.length} 个路径异常跳过（${r.skipped.slice(0, 3).join(', ')}${r.skipped.length > 3 ? ' 等' : ''}）`
+            : '';
+          specOutcome = {
+            ok: true, resolved: true,
+            reason: `spec 树已接受服务器版本：覆盖 ${r.overwritten} 个冲突文件${r.removed > 0 ? `、删除 ${r.removed} 个（服务器已删）` : ''}${skippedNote}，本地改动已放弃`,
+          };
+        } else {
+          specOutcome = { ok: false, resolved: false, reason: `spec 树 take-platform 失败: ${r.reason}（可重试；或手动对齐本地文件后 --keep-local）` };
+        }
+      } catch (err) {
+        specOutcome = { ok: false, resolved: false, reason: `spec 树 take-platform 异常: ${err.message}` };
+      }
     }
 
     // ── abort：两类标记一并清（本地 DB 与文件均不变，下次 push/pull 重新检测）──
@@ -1369,6 +1917,12 @@ export async function pullList(cwd) {
   return new SyncManager(cwd).pullList();
 }
 
+// X2（task-14 / FR-07 / FR-08）：spec 整树快照拉取便捷导出（index.js 顶层 pull --spec 命令用，
+// 与 SyncManager.pullSpecBundle 实例方法共用实现）。快照语义见实例方法 docstring（design §7.4）。
+export async function pullSpecBundle(cwd, opts) {
+  return new SyncManager(cwd).pullSpecBundle(opts);
+}
+
 // task-13 / D-002 / D-010 / D-013 / FR-05：冲突解决三选一（index.js platform resolve 子命令用）
 export async function resolve(changeName, mode, cwd) {
   return new SyncManager(cwd).resolve(changeName, mode);