sillyspec 3.27.9 → 3.27.12

package/src/sync.js

@@ -8,13 +8,13 @@
  * 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 { 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 +29,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 +208,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 +267,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 +566,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 +607,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 +651,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 +707,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 +798,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 +1070,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 +1380,171 @@ 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 };
+  }
+
   /**
    * 冲突解决三选一（task-13 / D-002 / D-010 / D-013 / FR-05）。
    * 读 task-12 写的 sync-conflict-<change>.json，按 mode 处理后必清冲突文件防累积（R-04 / constraints）。
@@ -1369,6 +1799,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);

package/src/verify-postcheck.js

@@ -579,10 +579,21 @@ export function extractKnownFailures(yamlText) {
   if (inline) {
     return inline[1].split(',').map(s => s.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean)
   }
-  const block = yaml.match(/^known_failures:\s*\n((?:[ \t]+-[ \t].+\n?)+)/m)
+  // 坑 verify-known-failures-comment-line-truncation（2026-08-28 连续踩两次）：块内注释行/空行
+  // 打断「连续列表项」的捕获链 → 只取到注释前的项，注释后的项静默丢失 → 清单残缺、
+  // verify 实测 remaining>0 假红。块定义放行注释行与空行（提取侧本就只认 `- ` 项行，
+  // 吸收进块的注释不影响结果）。
+  const block = yaml.match(/^known_failures:\s*\n((?:[ \t]+-[ \t].+\n?|[ \t]*#[^\n]*\n?|[ \t]*\n)+)/m)
   if (block) {
     return (block[1].match(/^[ \t]+-[ \t]+(.+)/gm) || [])
-      .map(s => s.replace(/^[ \t]+-[ \t]+/, '').trim().replace(/^['"]|['"]$/g, '').replace(/#.*$/, '').trim())
+      .map(s => {
+        const item = s.replace(/^[ \t]+-[ \t]+/, '').trim()
+        const full = item.match(/^(['"])(.*)\1$/)
+        if (full) return full[2] // 整体引号值原样保留（内部 # 不是注释）
+        const stripped = item.replace(/[ \t]+#.*$/, '').trim() // 行尾注释须 # 前有空白（YAML 语义），裸 # 不截
+        const q2 = stripped.match(/^(['"])(.*)\1$/)
+        return q2 ? q2[2] : stripped
+      })
       .filter(Boolean)
   }
   return []
@@ -591,9 +602,25 @@ export function extractKnownFailures(yamlText) {
 // 单条失败行标记（跨 pytest/jest/vitest/go/generic）。大小写不敏感。
 // 刻意用 FAIL/FAILED + 配合 SUMMARY_LINE_RE 排除汇总行：否则 pytest/jest 的
 // "N failed" 汇总会被误判为「需豁免的失败行」→ 永远 remaining>0 → known_failures 失效。
-const PER_TEST_FAIL_RE = /(FAILED|\bFAIL\b|✕|✗|✘|panic\s*:|assertionerror|traceback|---\s*fail|error:|exception)/i
-// 汇总/计数行（非单条失败）：pytest === 框、jest "Tests:"、裸 "N failed/passed"、go "FAILED in Ns" 等。
-const SUMMARY_LINE_RE = /(={2,}.*={2,}|^\s*\d+\s+(failed|passed|skipped|pending)\b|tests?\s*:|test\s+suites?\s*:|failed\s+in\s+\d)/i
+// ×(U+00D7) 是 vitest 失败行的实际前缀标记（✕✗✘ 是 jest/mocha 形态）。
+const PER_TEST_FAIL_RE = /(FAILED|\bFAIL\b|✕|✗|✘|×|panic\s*:|assertionerror|traceback|---\s*fail|error:|exception)/i
+// 汇总/计数行（非单条失败）：pytest === 框、jest "Tests:"、vitest "Test Files  N failed"/"Tests  N failed | M passed"
+// （无冒号形态）、裸 "N failed/passed"、go "FAILED in Ns"、pnpm "ELIFECYCLE Test failed" 退出横幅等。
+const SUMMARY_LINE_RE = /(={2,}.*={2,}|^\s*\d+\s+(failed|passed|skipped|pending)\b|tests?\s*:|test\s+suites?\s*:|^\s*(?:test\s+files|tests?)\s+\d|failed\s+in\s+\d|failed\s+tests\s+\d|elifecycle)/i
+// 控制台捕获噪声行（非失败信号）：vitest 把测试内 console 输出捕获为
+// `stderr | <file> > <测试名>` 横幅 + 后续内容行——挂在通过用例上的噪声里常含
+// error:/failed 字样（jsdom「Not implemented」警告、用例名本身带 failed 等），
+// 与失败信号（× 行 / FAIL 横幅 / 汇总计数）无关，全部剔除。
+const CONSOLE_CAPTURE_RE = /^\s*(?:stdout|stderr)\s*\|/
+const ENV_NOISE_RE = /not\s+implemented\s*:/i
+// 通过行（行首标记，剥 ANSI 后判定）：vitest/jest/mocha 的 ✓√✔ 前缀行 + jest 的 PASS 文件行。
+// 坑 verify-known-failures-pass-line-false-positive：FAILED/error:/exception 是子串匹配，
+// 通过行用例名恰含这些字样（如「✓ … 超时后 syncStatus=failed」）会被误判失败行——
+// 2710 用例套件 382 个"失败行"里 378 假阳性，known_failures 无法逐条枚举而实质失效。
+// 框架输出里通过行恒以通过标记开头、失败行恒以失败标记开头，行首判定即足以分离两类。
+const PASS_LINE_RE = /^\s*(?:[✓√✔]|PASS\b)/
+// ANSI 色码剥离（分类用）：TTY 捕获的输出里 ✓/× 前缀可能被色码包裹，行首锚定会失配。
+const ANSI_RE = /\x1b\[[0-9;]*[A-Za-z]/g
 
 /**
  * 把测试输出按行筛出「失败行」，再按 known_failures 模式分为已豁免 / 未豁免。
@@ -603,7 +630,15 @@ const SUMMARY_LINE_RE = /(={2,}.*={2,}|^\s*\d+\s+(failed|passed|skipped|pending)
  */
 export function partitionFailures(output, knownFailures) {
   const lines = String(output || '').split(/\r?\n/)
-  const failureLines = lines.filter(l => PER_TEST_FAIL_RE.test(l) && !SUMMARY_LINE_RE.test(l))
+  // 分类在剥 ANSI 后的行上做，返回保留原文（remaining 展示给 agent 时不变形）
+  const failureLines = lines.filter(l => {
+    if (PASS_LINE_RE.test(l)) return false
+    const bare = l.replace(ANSI_RE, '')
+    if (PASS_LINE_RE.test(bare)) return false
+    if (CONSOLE_CAPTURE_RE.test(bare)) return false
+    if (ENV_NOISE_RE.test(bare)) return false
+    return PER_TEST_FAIL_RE.test(bare) && !SUMMARY_LINE_RE.test(bare)
+  })
   const pats = (knownFailures || []).map(p => String(p).toLowerCase()).filter(Boolean)
   const exempted = []
   const remaining = []
@@ -1528,6 +1563,12 @@ export function printVerifyParityCheck(result) {
     console.warn(`   - ${m.method} ${m.path}  ← ${m.consumerFile}:${m.consumerLine}`)
   }
   if (result.missingBackend.length > 20) console.warn(`   …还有 ${result.missingBackend.length - 20} 个`)
+  // 全仓口径告警（坑 probe5-single-task-artifact-scope，2026-08-28 实证：diff/apply 清单都不可得
+  // 时回退全仓，全仓调用 × 本变更局部端点 = 大量假 missing，agent 照单记 FAIL 误导归档判定）
+  if (/\[scope: full-repo\]/.test(result.summary || '')) {
+    console.warn('   ⚠️  本次 scope 为 full-repo（diff 与 apply-pathspec 均不可得时的兜底）——missing 大概率是口径错配噪音而非真实 contract gap。')
+    console.warn('      先收窄复跑：sillyspec verify-probes --change <变更名>（change-diff/apply-pathspec 口径）再判定。')
+  }
   console.warn('   提示：检查是否后端漏实现，或前端调用了尚未实现的端点。确认无误可在 design.md 标注豁免。')
 }