sillyspec 3.26.11 → 3.26.14

package/src/sync.js

@@ -8,7 +8,8 @@
  * HTTP 请求：Node.js 原生 fetch（Node 22+）
  */
 
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, unlinkSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, unlinkSync, chmodSync } from 'fs';
+import { writeAtomicSync } from './fs-atomic.js';
 import { join } from 'path';
 import { resolvePlatformSpecDir } from './progress.js';
 import { safeGit } from './git-helper.js';
@@ -131,11 +132,17 @@ function replaceTopLevelSection(text, name, body) {
   return `${stripped}\n\n${name}:\n${body}\n`;
 }
 
-/** 文本级写 local.yaml（保留传入 text 的注释/结构）；确保 .sillyspec 目录存在。 */
+/** 文本级写 local.yaml（保留传入 text 的注释/结构）；确保 .sillyspec 目录存在。
+ *  原子写（fs-atomic 契约：local.yaml 被 hook/probe 等其他进程并发读，裸 writeFileSync 的
+ *  写入窗口可读到半截文件 → mcp 段解析失败回退 env → 误判 no-config 降级）。 */
 function writeLocalYamlRaw(cwd, text) {
   const dir = join(cwd, '.sillyspec');
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  writeFileSync(join(cwd, LOCAL_YAML), text, 'utf8');
+  const yamlPath = join(cwd, LOCAL_YAML);
+  writeAtomicSync(yamlPath, text, 'utf8');
+  // 体检 SEC-04：local.yaml 含明文 token，收紧为仅属主可读写。POSIX chmod 0600 生效；
+  // Windows 上 Node chmod 只映射只读位（近似 no-op），属可接受 best-effort
+  try { chmodSync(yamlPath, 0o600); } catch { /* chmod 失败不阻断连接流程 */ }
 }
 
 function parseSimpleYaml(content) {
@@ -195,11 +202,18 @@ function resolvePlatformUser(cwd, explicitUser) {
 
 // ── HTTP 辅助 ──
 
+// 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);
+  return external ? AbortSignal.any([timeoutSignal, external]) : timeoutSignal;
+}
+
 async function fetchJson(url, options = {}) {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  const signal = combineSignals(options.signal);
   try {
-    const res = await fetch(url, { ...options, signal: controller.signal });
+    const res = await fetch(url, { ...options, signal });
     if (!res.ok) {
       const text = await res.text().catch(() => '');
       console.warn(`[sync] ${options.method || 'GET'} ${url} → ${res.status} ${text.slice(0, 200)}`);
@@ -212,13 +226,11 @@ async function fetchJson(url, options = {}) {
     return null;
   } catch (err) {
     if (err.name === 'AbortError') {
-      console.warn(`[sync] ${url} 请求超时 (${REQUEST_TIMEOUT_MS}ms)`);
+      console.warn(`[sync] ${url} 请求超时/中断 (${REQUEST_TIMEOUT_MS}ms 上限或外部熔断)`);
     } else {
       console.warn(`[sync] ${url} 请求失败: ${err.message}`);
     }
     return null;
-  } finally {
-    clearTimeout(timer);
   }
 }
 
@@ -228,10 +240,9 @@ async function fetchJson(url, options = {}) {
  * 仅 sync() 的 progress POST 使用（识别 base_ts 乐观锁冲突，D-015 / task-09）；其余调用仍走 fetchJson。
  */
 async function fetchJsonWithStatus(url, options = {}) {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  const signal = combineSignals(options.signal);
   try {
-    const res = await fetch(url, { ...options, signal: controller.signal });
+    const res = await fetch(url, { ...options, signal });
     const text = await res.text().catch(() => '');
     let body = null;
     if (text) {
@@ -243,13 +254,11 @@ async function fetchJsonWithStatus(url, options = {}) {
     return { ok: res.ok, status: res.status, body };
   } catch (err) {
     if (err.name === 'AbortError') {
-      console.warn(`[sync] ${url} 请求超时 (${REQUEST_TIMEOUT_MS}ms)`);
+      console.warn(`[sync] ${url} 请求超时/中断 (${REQUEST_TIMEOUT_MS}ms 上限或外部熔断)`);
     } else {
       console.warn(`[sync] ${url} 请求失败: ${err.message}`);
     }
     return { ok: false, status: 0, body: null };
-  } finally {
-    clearTimeout(timer);
   }
 }
 
@@ -268,8 +277,19 @@ export class SyncManager {
    * @param {string} [user] - 推送者身份（可空，回退 git user.name / env，见 resolvePlatformUser）
    */
   async connect(url, token, user) {
+    if (!token) {
+      // 体检 HUB-02：falsy token 不允许 connect——health ping 无鉴权会"连接成功"，
+      // 但 local.yaml 会落盘字符串 "undefined"，后续所有同步持续 401
+      console.error('[sync] 缺少 token，拒绝连接（请在平台获取 token 后带 --token 重试）');
+      return false;
+    }
     // 验证连接
     const normalizedUrl = url.replace(/\/+$/, '');
+    // 体检 SEC-04：非 https 且非本机回环时 Bearer token 明文上线——MCP client 侧
+    // （sillyhub-mcp/client.js 构造器）早有同款 warn，sync 侧此前完全静默
+    if (!/^https:\/\//i.test(normalizedUrl) && !/^http:\/\/(localhost|127\.0\.0\.1|\[::1\])(:|\/|$)/i.test(normalizedUrl)) {
+      console.warn(`[sync] platform.url 非 https（${normalizedUrl.slice(0, 60)}），同步 token 将明文传输——请确认为受控内网环境`);
+    }
     const healthUrl = `${normalizedUrl}/api/health`;
     const result = await fetchJson(healthUrl);
     if (result === null) {
@@ -347,11 +367,14 @@ export class SyncManager {
           // 删段后纯空白（无任何段也无注释）→ 删除整个文件；注释算内容，有注释则保留
           try { unlinkSync(p); } catch { /* best effort */ }
         } else {
-          writeFileSync(p, newText, 'utf8');
+          writeAtomicSync(p, newText, 'utf8');
         }
       }
     }
-    // 三清之二/三：指针 + 接管声明（disconnect 是声明的唯一退出路径——design.md §5.4）
+    // 三清之二/三：指针 + 接管声明（disconnect 是声明的唯一退出路径——design.md §5.4）。
+    // HUB-12 有意不清 .sillyspec-platform-cleaned marker：它防的是「重新接入平台时 init
+    // 重复做残留清理」——disconnect 后重连若清掉 marker，init 会对现在装着本地数据的
+    // .sillyspec 再跑一次平台残留清理（误删风险）。marker 跨 disconnect 存活是保护语义。
     let cleaned = [];
     for (const f of ['.sillyspec-platform.json', PLATFORM_MANAGED_FILENAME]) {
       const fp = join(this.cwd, f);
@@ -368,8 +391,15 @@ export class SyncManager {
    * 读取 ProgressManager.serializeForSync() 的六表 JSON，POST 到平台。
    * 元字段（user/base_ts/pushed_at）走 HTTP header，body 保持裸 JSON（D-015，sillyhub 老版零回归）。
    * 同步完成后更新 changes 表的 platform_last_sync 字段；409 冲突读回平台最新 JSON（task-12 完整冲突处理）。
+   *
+   * push 409 自竞态自愈（坑 2026-08-19-platform-sync-base-ts-silent-conflict 根治侧）：
+   * 同机多进程（CLI + daemon）并发 push 时，B 进程持旧 base_ts POST 撞 A 进程刚推完的 409——
+   * 但 A 的成功回填就写在本机共享 DB。409 时 fresh 重读 DB：base_ts 已 ≥ 平台 409 回执 ts
+   * ⇒ 赢者是自己人 → 刷新 base_ts 重试一次即收敛，不再落冲突文件卡死人工 resolve。
+   * 外来推送（他机/他用户）不可能推进本机 DB 的 base_ts → 走原冲突路径，无误放行。
    */
-  async sync(changeName) {
+  async sync(changeName, opts = {}) {
+    const { fromResolve = false } = opts;
     const platform = this._getPlatform();
     if (!platform) {
       debugLog('[sync] 未连接平台（本地合法状态）；如需平台同步：sillyspec platform connect');
@@ -388,112 +418,178 @@ export class SyncManager {
       console.warn(`[sync] 变更目录不存在（可能是已归档，继续从 DB 同步最终状态）: ${changeName}`);
     }
 
-    // 读取 progress 数据（serializeForSync 六表裸 JSON，task-02 / D-005@v2，替代 read() 聚合视图）
-    let progressData;
-    try {
-      const { ProgressManager } = await import('./progress.js');
-      const pm = new ProgressManager({ specDir: safePlatformSpecDir(this.cwd) });
-      progressData = pm.serializeForSync(this.cwd, changeName);
-    } catch (err) {
-      console.warn(`[sync] 读取 progress 失败 (${changeName}): ${err.message}`);
-      return { synced: 0, errors: [`读取 progress 失败: ${err.message}`] };
-    }
-    if (progressData === null) {
-      console.warn(`[sync] 变更无进度数据 (无活跃进度): ${changeName}`);
-      return { synced: 0, errors: [`变更无进度数据: ${changeName}`] };
-    }
+    const MAX_PUSH_ATTEMPTS = 2;
+    for (let attempt = 1; attempt <= MAX_PUSH_ATTEMPTS; attempt++) {
+      // 读取 progress 数据（serializeForSync 六表裸 JSON，task-02 / D-005@v2，替代 read() 聚合视图）。
+      // 每次 attempt 重新 serialize：自愈重试时本地 DB 可能已被并发进程推进，base_ts/内容都要刷新
+      let progressData;
+      try {
+        const { ProgressManager } = await import('./progress.js');
+        const pm = new ProgressManager({ specDir: safePlatformSpecDir(this.cwd) });
+        progressData = pm.serializeForSync(this.cwd, changeName);
+      } catch (err) {
+        console.warn(`[sync] 读取 progress 失败 (${changeName}): ${err.message}`);
+        return { synced: 0, errors: [`读取 progress 失败: ${err.message}`] };
+      }
+      if (progressData === null) {
+        console.warn(`[sync] 变更无进度数据 (无活跃进度): ${changeName}`);
+        return { synced: 0, errors: [`变更无进度数据: ${changeName}`] };
+      }
 
-    // 元字段走 HTTP header（D-015 / task-09）：body 保持裸六表 JSON，sillyhub 老版忽略 header 零回归
-    const headers = {
-      'Content-Type': 'application/json',
-      Authorization: `Bearer ${platform.token}`,
-    };
-    const pushedAt = new Date().toISOString();
-    // 推送者身份（task-08）：local.yaml platform.user 显式配置优先，缺省回退
-    // resolvePlatformUser（git user.name > env USER/USERNAME，与 connect 写入侧同口径）。
-    // 修 last_pusher 空：此前仅 platform.user 配置时发送，本地直跑场景 local.yaml
-    // 常无 user 字段 → header 缺失 → 平台 last_pusher 恒空（2026-08-19 坑文档改进点 4）。
-    const pushUser = platform.user || resolvePlatformUser(this.cwd) || null;
-    if (pushUser) headers['X-SillySpec-User'] = pushUser;
-    const baseTs = progressData.changes && progressData.changes[0] && progressData.changes[0].last_synced_platform_ts;
-    if (baseTs) headers['X-SillySpec-Base-Ts'] = baseTs; // base_ts 乐观锁（NULL=首次同步不设，平台接受首次 push）
-    headers['X-SillySpec-Pushed-At'] = pushedAt; // 平台存 last_pushed_at，作下次其他用户 push 的 base_ts 比对基准
-
-    // POST 到平台（带状态码版本：识别 409 冲突，读回平台最新 JSON）。changeName encode 对齐 pull（:673）
-    const syncUrl = `${platform.url}/api/changes/${encodeURIComponent(changeName)}/progress`;
-    const res = await fetchJsonWithStatus(syncUrl, {
-      method: 'POST',
-      headers,
-      body: JSON.stringify(progressData),
-    });
+      // 元字段走 HTTP header（D-015 / task-09）：body 保持裸六表 JSON，sillyhub 老版忽略 header 零回归
+      const headers = {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${platform.token}`,
+      };
+      const pushedAt = new Date().toISOString();
+      // 推送者身份（task-08）：local.yaml platform.user 显式配置优先，缺省回退
+      // resolvePlatformUser（git user.name > env USER/USERNAME，与 connect 写入侧同口径）。
+      // 修 last_pusher 空：此前仅 platform.user 配置时发送，本地直跑场景 local.yaml
+      // 常无 user 字段 → header 缺失 → 平台 last_pusher 恒空（2026-08-19 坑文档改进点 4）。
+      const pushUser = platform.user || resolvePlatformUser(this.cwd) || null;
+      if (pushUser) headers['X-SillySpec-User'] = pushUser;
+      const baseTs = progressData.changes && progressData.changes[0] && progressData.changes[0].last_synced_platform_ts;
+      if (baseTs) headers['X-SillySpec-Base-Ts'] = baseTs; // base_ts 乐观锁（NULL=首次同步不设，平台接受首次 push）
+      headers['X-SillySpec-Pushed-At'] = pushedAt; // 平台存 last_pushed_at，作下次其他用户 push 的 base_ts 比对基准
+
+      // POST 到平台（带状态码版本：识别 409 冲突，读回平台最新 JSON）。changeName encode 对齐 pull（:673）
+      const syncUrl = `${platform.url}/api/changes/${encodeURIComponent(changeName)}/progress`;
+      const res = await fetchJsonWithStatus(syncUrl, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(progressData),
+        signal: opts.signal, // HUB-09：熔断 abort 传到底层请求
+      });
+
+      if (res.ok) {
+        // 更新 platform_last_sync + 推进 base_ts（ql-20260818-008：值优先平台回执 last_pushed_at，
+        // 缺省用本次 pushedAt——服务器 _apply 存的就是客户端 X-SillySpec-Pushed-At 原值，回写一致。
+        // 修复前该列从不写，下次 push 永不带 X-SillySpec-Base-Ts、pull 脏度检测恒 false）
+        // 回填加固：共享 SQLite 并发（daemon+CLI）下 WAL 忙窗口可能偶发失败——重试一次，
+        // 仍失败打醒目 warn（base_ts 停留在旧值，下次 push 会 409，届时自竞态自愈会收敛）
+        let backfilled = false;
+        for (let bt = 1; bt <= 2 && !backfilled; bt++) {
+          try {
+            const { ProgressManager } = await import('./progress.js');
+            const pm = new ProgressManager({ specDir: safePlatformSpecDir(this.cwd) });
+            const ackTs = res.body && typeof res.body.last_pushed_at === 'string' ? res.body.last_pushed_at : pushedAt;
+            pm._updatePlatformLastSync(this.cwd, changeName, ackTs);
+            backfilled = true;
+          } catch (err) {
+            if (bt === 2) {
+              console.warn(`⚠️ [sync] base_ts 回填失败（下次 push 可能 409，自愈机制会处理）: ${err.message}`);
+            } else {
+              await new Promise((r) => setTimeout(r, 200));
+            }
+          }
+        }
 
-    if (!res.ok) {
-      // 409 = base_ts 乐观锁冲突（平台已有更新）；读回平台最新 JSON 供 task-12 完整冲突处理
-      if (res.status === 409) {
-        // 醒目冲突横幅（坑 2026-08-19-platform-sync-base-ts-silent-conflict 改进点 2）：
-        // 此前仅单行 warn，冲突文件静默落 .runtime——同步已卡死但 Agent/用户无从察觉，
-        // 平台页面永久停在旧阶段。横幅明确告知「已卡死 + 卡死原因 + 恢复命令」，不能只落文件。
-        console.warn('');
-        console.warn('⚠️⚠️⚠️════════════════════════════════════════════════════');
-        console.warn(`⚠️ 平台同步冲突：变更「${changeName}」推送被拒（base_ts 过期，平台已有更新）`);
-        console.warn('⚠️ 该变更的自动同步已卡死，不会自愈——需人工 resolve 才能恢复：');
-        console.warn(`⚠️   1. sillyspec platform status     # 查看未决冲突`);
-        console.warn(`⚠️   2. sillyspec platform resolve ${changeName} --keep-local | --take-platform | --abort`);
-        console.warn(`⚠️   3. sillyspec platform sync --change ${changeName}`);
-        console.warn('⚠️ 冲突详情已落盘: .sillyspec/.runtime/sync-conflict-' + changeName + '.json');
-        console.warn('⚠️⚠️⚠️════════════════════════════════════════════════════');
-        // 平台 409 响应 { conflict:true, platform_progress, last_pushed_at }，platform_progress 即平台最新 progress JSON
-        const platformProgress = res.body && res.body.platform_progress ? res.body.platform_progress : res.body;
-        const platformLastPushedAt = (res.body && res.body.last_pushed_at) || null;
-        // 本地脏度（progressData 是 serializeForSync 输出，changes[0] 含 last_local_modified_ts）
-        const localModified = (progressData.changes && progressData.changes[0] && progressData.changes[0].last_local_modified_ts) || null;
-        // 写冲突文件（task-12 / D-002）：base_ts=本次 push 的 base，强制提示走 resolve
-        const conflictPath = this._writeConflictFile(changeName, {
-          base_ts: baseTs || null,
-          local_modified_ts: localModified,
-          platform_last_pushed_at: platformLastPushedAt,
-          platform_progress: platformProgress,
-        });
-        return { synced: 0, errors: [`冲突: ${changeName}`], conflict: true, platform_progress: platformProgress, conflictPath };
+        console.log(`[sync] 已同步变更: ${changeName}`);
+
+        // 2026-08-16-auto-sync-from-repo：进度上行成功后顺带推四件套文档（best-effort）。
+        // 根因：run 流程此前只推进度不推文档（本文件头注释），本地直跑 sillyspec 的产出
+        // 文档永远不自动到平台（变更中心"进度到了文档没到"）。生产者直连，不依赖 daemon
+        // 缓存链路。失败仅 debugLog——文档同步失败不得影响进度上行的返回值与流程；
+        // 四件套全缺失时 syncDocuments 内部已有跳过（syncedCount===0 提前返回，不调端点）。
+        try {
+          await this.syncDocuments(changeName, { signal: opts.signal });
+        } catch (err) {
+          debugLog(`[sync] 文档同步失败（不影响进度）: ${changeName}: ${err.message}`);
+        }
+
+        // 2026-08-17-spec-file-incremental-sync：进度上行+文档直推成功后顺带推整个 spec 树
+        // （plan.md、tasks/、module-impact.md 等），让变更中心文件树自动更新。
+        // 无 daemon 时 CLI 短进程无本地清单缓存，以服务器清单为锚做增量 diff。
+        // 树根与进度锚点同源（safePlatformSpecDir，平台模式 → specRoot）：此前硬编码
+        // cwd/.sillyspec，平台模式下该目录只有 local.yaml（被 walk 排除）→ 本地树恒空
+        // → 服务器清单全量 delete（BUG-01，computeSpecOps 护栏为第二道防线）。
+        try {
+          await syncSpecTree(safePlatformSpecDir(this.cwd) || join(this.cwd, '.sillyspec'), this._getPlatform(), changeName, { signal: opts.signal });
+        } catch (err) {
+          debugLog(`[sync] spec 树增量同步失败（不影响进度）: ${changeName}: ${err.message}`);
+        }
+
+        return { synced: 1, errors: [] };
       }
-      return { synced: 0, errors: [`同步请求失败: ${changeName}`] };
-    }
 
-    // 更新 platform_last_sync + 推进 base_ts（ql-20260818-008：值优先平台回执 last_pushed_at，
-    // 缺省用本次 pushedAt——服务器 _apply 存的就是客户端 X-SillySpec-Pushed-At 原值，回写一致。
-    // 修复前该列从不写，下次 push 永不带 X-SillySpec-Base-Ts、pull 脏度检测恒 false）
-    try {
-      const { ProgressManager } = await import('./progress.js');
-      const pm = new ProgressManager({ specDir: safePlatformSpecDir(this.cwd) });
-      const ackTs = res.body && typeof res.body.last_pushed_at === 'string' ? res.body.last_pushed_at : pushedAt;
-      pm._updatePlatformLastSync(this.cwd, changeName, ackTs);
-    } catch (err) {
-      console.warn(`[sync] 更新 platform_last_sync 失败: ${err.message}`);
-    }
+      if (res.status !== 409) {
+        return { synced: 0, errors: [`同步请求失败: ${changeName}`] };
+      }
 
-    console.log(`[sync] 已同步变更: ${changeName}`);
+      // ── 409 = base_ts 乐观锁冲突（平台已有更新）──
+      // 平台 409 响应 { conflict:true, platform_progress, last_pushed_at }，platform_progress 即平台最新 progress JSON
+      const platformProgress = res.body && res.body.platform_progress ? res.body.platform_progress : res.body;
+      const platformLastPushedAt = (res.body && res.body.last_pushed_at) || null;
+
+      // 自竞态自愈：fresh 重读本机 DB base_ts，若已被并发进程回填到 ≥ 平台 409 回执 ts，
+      // 说明赢者是本机自己人——刷新 base_ts 重试一次即收敛，不落冲突文件（外来推送不可能
+      // 推进本机 DB 的 base_ts，不满足条件自然落回下方真冲突分支，零误放行）
+      if (attempt < MAX_PUSH_ATTEMPTS && await this._localBaseTsCovers(changeName, platformLastPushedAt)) {
+        console.warn(`⚠️ [sync] push 409 自竞态判定：本机并发推送已回填 base_ts（平台 ts=${platformLastPushedAt}），刷新后自动重试`);
+        continue;
+      }
 
-    // 2026-08-16-auto-sync-from-repo：进度上行成功后顺带推四件套文档（best-effort）。
-    // 根因：run 流程此前只推进度不推文档（本文件头注释），本地直跑 sillyspec 的产出
-    // 文档永远不自动到平台（变更中心"进度到了文档没到"）。生产者直连，不依赖 daemon
-    // 缓存链路。失败仅 debugLog——文档同步失败不得影响进度上行的返回值与流程；
-    // 四件套全缺失时 syncDocuments 内部已有跳过（syncedCount===0 提前返回，不调端点）。
-    try {
-      await this.syncDocuments(changeName);
-    } catch (err) {
-      debugLog(`[sync] 文档同步失败（不影响进度）: ${changeName}: ${err.message}`);
+      // resolve --keep-local 的自动重推再撞 409：不落新冲突文件、不打「已卡死」横幅——
+      // 原 conflict 已按用户裁决处理完（base_ts 已推进），此刻的 409 只是「平台在用户裁决期间
+      // 又动了」；立即落新文件会破坏「keep-local 清冲突文件回 clean」的生命周期契约（冲突文件
+      // 代表待人工三选一的未决状态，而用户刚做完选择）。下次常规同步会按新 base 重新判定，
+      // 真有新分歧自然再进 conflict 态。
+      if (fromResolve) {
+        console.warn(`⚠️ [sync] keep-local 自动重推被拒（平台又有更新，ts=${platformLastPushedAt}）；base_ts 已推进，下次常规同步将重新判定`);
+        return { synced: 0, errors: [`keep-local 自动重推被拒: ${changeName}`], conflict: true, platform_progress: platformProgress, suppressedConflictFile: true };
+      }
+
+      // 醒目冲突横幅（坑 2026-08-19-platform-sync-base-ts-silent-conflict 改进点 2）：
+      // 此前仅单行 warn，冲突文件静默落 .runtime——同步已卡死但 Agent/用户无从察觉，
+      // 平台页面永久停在旧阶段。横幅明确告知「已卡死 + 卡死原因 + 恢复命令」，不能只落文件。
+      console.warn('');
+      console.warn('⚠️⚠️⚠️════════════════════════════════════════════════════');
+      console.warn(`⚠️ 平台同步冲突：变更「${changeName}」推送被拒（base_ts 过期，平台已有更新）`);
+      console.warn('⚠️ 该变更的自动同步已卡死，不会自愈——需人工 resolve 才能恢复：');
+      console.warn(`⚠️   1. sillyspec platform status     # 查看未决冲突`);
+      console.warn(`⚠️   2. sillyspec platform resolve ${changeName} --keep-local | --take-platform | --abort`);
+      console.warn(`⚠️   3. sillyspec platform sync --change ${changeName}`);
+      console.warn('⚠️⚠️⚠️════════════════════════════════════════════════════');
+      // 本地脏度（progressData 是 serializeForSync 输出，changes[0] 含 last_local_modified_ts）
+      const localModified = (progressData.changes && progressData.changes[0] && progressData.changes[0].last_local_modified_ts) || null;
+      // 写冲突文件（task-12 / D-002）：base_ts=本次 push 的 base，强制提示走 resolve
+      const conflictPath = this._writeConflictFile(changeName, {
+        base_ts: baseTs || null,
+        local_modified_ts: localModified,
+        platform_last_pushed_at: platformLastPushedAt,
+        platform_progress: platformProgress,
+      });
+      console.warn(`⚠️ 冲突详情已落盘: ${conflictPath}`);
+      return { synced: 0, errors: [`冲突: ${changeName}`], conflict: true, platform_progress: platformProgress, conflictPath };
     }
 
-    // 2026-08-17-spec-file-incremental-sync：进度上行+文档直推成功后顺带推整个 spec 树
-    // （plan.md、tasks/、module-impact.md 等），让变更中心文件树自动更新。
-    // 无 daemon 时 CLI 短进程无本地清单缓存，以服务器清单为锚做增量 diff。
+    // 循环耗尽（自愈重试后仍 409——两次都撞且第二次非自竞态；理论上第二次会落上方真冲突分支返回，
+    // 此行只作结构兜底）
+    return { synced: 0, errors: [`同步重试耗尽（仍冲突）: ${changeName}`] };
+  }
+
+  /**
+   * 自竞态判定辅助：fresh 读本地 DB 的 last_synced_platform_ts（base_ts），判断它是否已覆盖
+   * 平台 409 回执的 last_pushed_at（字符串字典序比较，契约 §4.2——ISO 8601 字典序 == 时间序）。
+   * 已覆盖 ⇒ 打赢 409 的推送来自本机并发进程（其成功回填写的就是这个共享 DB）。
+   * @param {string} changeName
+   * @param {string|null} platformTs 409 回执 last_pushed_at
+   * @returns {Promise<boolean>}
+   */
+  async _localBaseTsCovers(changeName, platformTs) {
+    if (!platformTs) return false;
     try {
-      await syncSpecTree(join(this.cwd, '.sillyspec'), this._getPlatform(), changeName);
-    } catch (err) {
-      debugLog(`[sync] spec 树增量同步失败（不影响进度）: ${changeName}: ${err.message}`);
+      const { ProgressManager } = await import('./progress.js');
+      const pm = new ProgressManager({ specDir: safePlatformSpecDir(this.cwd) });
+      const row = pm._ensureDB(this.cwd).getDb().prepare(
+        'SELECT last_synced_platform_ts FROM changes WHERE name = ?'
+      ).get(changeName);
+      const localTs = row && row.last_synced_platform_ts;
+      if (!localTs) return false;
+      return localTs >= platformTs;
+    } catch {
+      return false; // 读失败按非自竞态处理（fail-closed 到真冲突分支）
     }
-
-    return { synced: 1, errors: [] };
   }
 
   /**
@@ -516,7 +612,10 @@ export class SyncManager {
       return { synced: 0, errors: ['未指定变更名称'] };
     }
 
-    const changeDir = join(this.cwd, CHANGES_DIR, changeName);
+    // 树根与进度/spec 树同源（safePlatformSpecDir，BUG-01 同族）：此前硬编码 cwd/.sillyspec/changes，
+    // 平台模式（specRoot 指向外部）下路径不存在 → syncDocuments 恒报「变更不存在」且调用方不查
+    // 返回值 → 文档在平台模式下静默永不同步。
+    const changeDir = join(safePlatformSpecDir(this.cwd) || join(this.cwd, '.sillyspec'), 'changes', changeName);
     if (!existsSync(changeDir)) {
       console.warn(`[sync] 变更不存在: ${changeName}`);
       return { synced: 0, errors: [`变更不存在: ${changeName}`] };
@@ -558,6 +657,7 @@ export class SyncManager {
         Authorization: `Bearer ${platform.token}`,
       },
       body: JSON.stringify(documents),
+      signal: opts.signal, // HUB-09：熔断 abort 传到底层请求
     });
 
     if (!result) {
@@ -677,6 +777,31 @@ export class SyncManager {
     }
   }
 
+  // ── HUB-08：spec 树冲突文件（spec-sync-conflict-<change>.json，由 spec-sync.js 写入）──
+
+  /** 读取 spec 树冲突文件；无/损坏返回 null */
+  readSpecConflictFile(changeName) {
+    const specDir = safePlatformSpecDir(this.cwd);
+    if (!specDir) return null;
+    const p = join(specDir, '.runtime', `spec-sync-conflict-${changeName}.json`);
+    if (!existsSync(p)) return null;
+    try {
+      return JSON.parse(readFileSync(p, 'utf8'));
+    } catch {
+      return null;
+    }
+  }
+
+  /** 删除 spec 树冲突文件 */
+  clearSpecConflictFile(changeName) {
+    const specDir = safePlatformSpecDir(this.cwd);
+    if (!specDir) return false;
+    const p = join(specDir, '.runtime', `spec-sync-conflict-${changeName}.json`);
+    if (!existsSync(p)) return false;
+    try { unlinkSync(p); return true; }
+    catch { return false; }
+  }
+
   /**
    * 删除冲突文件（resolve 完成后清理，task-13 用）。
    * @returns {boolean} 是否删除（文件不存在返回 false）
@@ -747,6 +872,7 @@ export class SyncManager {
     const progressUrl = `${platform.url}/api/changes/${encodeURIComponent(changeName)}/progress`;
     const result = await fetchJson(progressUrl, {
       headers: { Authorization: `Bearer ${platform.token}` },
+      signal: opts.signal, // HUB-09：熔断 abort 传到底层请求
     });
     if (result === null) {
       // sillyhub 未就绪 / 404 / 网络失败均 fetchJson 返回 null → Best Effort 降级
@@ -806,7 +932,6 @@ export class SyncManager {
         console.warn(`⚠️   1. sillyspec platform status     # 查看未决冲突`);
         console.warn(`⚠️   2. sillyspec platform resolve ${changeName} --keep-local | --take-platform | --abort`);
         console.warn(`⚠️   3. sillyspec platform sync --change ${changeName}`);
-        console.warn('⚠️ 冲突详情已落盘: .sillyspec/.runtime/sync-conflict-' + changeName + '.json');
         console.warn('⚠️⚠️⚠️════════════════════════════════════════════════════');
         // 写冲突文件（task-12 / D-002）：强制提示，绝不 auto-merge
         const conflictPath = this._writeConflictFile(changeName, {
@@ -815,6 +940,7 @@ export class SyncManager {
           platform_last_pushed_at: platformPushedAt,
           platform_progress: platformProgress,
         });
+        console.warn(`⚠️ 冲突详情已落盘: ${conflictPath}`); // HUB-12d：真实落点（平台模式在 specRoot/.runtime），勿硬编码
         return { ok: false, imported: false, conflict: true, reason: `冲突: ${changeName} 本地脏且平台更新`, conflictPath };
       }
       // ql-20260818-008：自动注入点（triggerPull/triggerPullActiveChange）保守守卫——本地有未同步
@@ -858,12 +984,16 @@ export class SyncManager {
    */
   async resolve(changeName, mode) {
     const cf = this.readConflictFile(changeName);
-    if (!cf) {
-      return { ok: false, resolved: false, reason: `无可解决冲突: ${changeName}（无 sync-conflict 文件）` };
+    const specCf = this.readSpecConflictFile(changeName);
+    if (!cf && !specCf) {
+      return { ok: false, resolved: false, reason: `无可解决冲突: ${changeName}（无 sync-conflict / spec-sync-conflict 文件）` };
     }
-    const platformPushedAt = cf.platform_last_pushed_at || null;
+    const platformPushedAt = (cf && cf.platform_last_pushed_at) || null;
 
-    if (mode === 'keep-local') {
+    // HUB-08：resolve 同时管辖进度冲突（sync-conflict-*）与 spec 树冲突（spec-sync-conflict-*），
+    // 各自产出 outcome 后合并返回；abort 统一清两类标记。
+    let progressOutcome = null;
+    if (mode === 'keep-local' && cf) {
       // base_ts 推进到平台最新 last_pushed_at；本地 DB 不 import（用户本地为准，后续手动 push）。
       // MAX() 单调防回退（坑 2026-08-19-resolve-keep-local-base-ts-rollback）：冲突文件是历史快照，
       // 其 platform_last_pushed_at 可能早于 DB 已由后续成功 push 回填的 base_ts——无条件覆盖会把
@@ -873,17 +1003,40 @@ export class SyncManager {
         const { ProgressManager } = await import('./progress.js');
         const pm = new ProgressManager({ specDir: safePlatformSpecDir(this.cwd) });
         const db = pm._ensureDB(this.cwd).getDb();
-        db.prepare('UPDATE changes SET last_synced_platform_ts = MAX(?, COALESCE(last_synced_platform_ts, ?)) WHERE name = ?')
+        // 参数侧同样 COALESCE（坑 keep-local-base-ts-null-param）：SQLite 标量 MAX() 任一参数
+        // 为 NULL 即返回 NULL——冲突文件 platform_last_pushed_at 为 null 时 MAX(NULL, 旧值)
+        // 会把已回填的 base_ts 清空，恰好违背本注释的单调防回退意图。
+        db.prepare('UPDATE changes SET last_synced_platform_ts = MAX(COALESCE(?, last_synced_platform_ts), COALESCE(last_synced_platform_ts, ?)) WHERE name = ?')
           .run(platformPushedAt, platformPushedAt, changeName);
       } catch (err) {
         return { ok: false, resolved: false, reason: `keep-local 更新 base_ts 失败: ${err.message}` };
       }
       this.clearConflictFile(changeName);
-      return { ok: true, resolved: true, mode: 'keep-local', reason: '保留本地，base_ts 已推进到平台最新（后续请 platform sync push 本地）' };
+      // 自动重推闭环（坑 2026-08-19-platform-sync-base-ts-silent-conflict 收尾侧）：keep-local 语义 =
+      // 本地为准，必然收尾是把本地推上平台。此前停在「后续请手动 platform sync」——忘了推，
+      // 期间他人再推 → 下次自动同步又 409 落冲突文件（「冲突再现」的根源之一）。resolve 成功即
+      // 自动 push 一次闭环；真撞上外来更新时软提示（fromResolve 抑制新冲突文件——冲突文件代表
+      // 待人工三选一的未决状态，用户刚做完选择，下次常规同步按新 base 重新判定）。
+      let repush = null;
+      try {
+        repush = await this.sync(changeName, { fromResolve: true });
+      } catch (err) {
+        debugLog(`[sync] keep-local 自动重推异常（不阻断 resolve 结果）: ${changeName}: ${err.message}`);
+      }
+      if (repush && repush.synced === 1) {
+        progressOutcome = { ok: true, resolved: true, reason: '保留本地，并已自动推送平台——冲突闭环，无需再手动 sync' };
+      } else if (repush && repush.conflict) {
+        progressOutcome = { ok: true, resolved: true, reason: '保留本地，base_ts 已推进；自动重推被拒（平台在裁决期间又有更新），下次常规同步将重新判定' };
+      } else {
+        progressOutcome = { ok: true, resolved: true, reason: '保留本地，base_ts 已推进；自动重推未成功（未连接/网络），请手动 sillyspec platform sync --change ' + changeName };
+      }
     }
 
-    if (mode === 'take-platform') {
-      // 用冲突文件的 platform_progress 调 import 覆盖本地（保隔离：import 不覆盖 isolation_*）
+    if (mode === 'take-platform' && cf) {
+      // 用冲突文件的 platform_progress 调 import 覆盖本地（保隔离：import 不覆盖 isolation_*）。
+      // fail-closed（坑 take-platform-empty-import）：缺 platform_progress 时必须直接返回——
+      // { ...null } 展开为 {}，import 会照常跑完整事务（DELETE stages 后按空 JSON 重建 =
+      // 清空本地进度），返回值却报 ok:false「未执行」，用户以为无事发生实则数据已丢。
       if (!cf.platform_progress) {
         return { ok: false, resolved: false, reason: '冲突文件缺 platform_progress，无法 take-platform（建议先 platform pull）' };
       }
@@ -892,19 +1045,57 @@ export class SyncManager {
         const pm = new ProgressManager({ specDir: safePlatformSpecDir(this.cwd) });
         pm.import(this.cwd, { ...cf.platform_progress, pushed_at: platformPushedAt || new Date().toISOString() }, changeName);
       } catch (err) {
-        return { ok: false, resolved: false, reason: `take-platform import 失败: ${err.message}` };
+        progressOutcome = { ok: false, resolved: false, reason: `take-platform import 失败: ${err.message}` };
+      }
+      if (progressOutcome === null) {
+        this.clearConflictFile(changeName);
+        progressOutcome = { ok: true, resolved: true, reason: '已用平台进度覆盖本地' };
       }
-      this.clearConflictFile(changeName);
-      return { ok: true, resolved: true, mode: 'take-platform', reason: '已用平台进度覆盖本地' };
     }
 
+    // ── spec 树冲突处置（HUB-08）──
+    let specOutcome = null;
+    if (specCf && mode === 'keep-local') {
+      // keep-local = 本地胜出：重新 GET 清单重定 base 后 POST 本地内容（last-writer-wins），
+      // 成功清冲突文件闭环；仍冲突（平台又有更新）保留文件待下次裁决
+      try {
+        const r = await syncSpecTree(safePlatformSpecDir(this.cwd) || join(this.cwd, '.sillyspec'), this._getPlatform(), changeName);
+        if (!r.conflict) {
+          this.clearSpecConflictFile(changeName);
+          specOutcome = { ok: true, resolved: true, reason: 'spec 树已以本地为准重定基线重推，冲突闭环' };
+        } else {
+          specOutcome = { ok: true, resolved: false, reason: 'spec 树重推仍冲突（平台在裁决期间又有更新），冲突文件保留待下次裁决' };
+        }
+      } catch (err) {
+        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' };
+    }
+
+    // ── abort：两类标记一并清（本地 DB 与文件均不变，下次 push/pull 重新检测）──
     if (mode === 'abort') {
-      // 本地 DB 与 base_ts 均不变，仅清冲突文件（放弃本次同步，下次 push/pull 会重新检测）
-      this.clearConflictFile(changeName);
+      if (cf) this.clearConflictFile(changeName);
+      if (specCf) this.clearSpecConflictFile(changeName);
       return { ok: true, resolved: true, mode: 'abort', reason: '放弃本次同步，本地不变' };
     }
 
-    return { ok: false, resolved: false, reason: `未知 resolve 模式: ${mode}（--keep-local / --take-platform / --abort）` };
+    if (mode !== 'keep-local' && mode !== 'take-platform') {
+      return { ok: false, resolved: false, reason: `未知 resolve 模式: ${mode}（--keep-local / --take-platform / --abort）` };
+    }
+
+    // ── 合并两类冲突的处置结果 ──
+    const outcomes = [progressOutcome, specOutcome].filter(Boolean);
+    if (outcomes.length === 0) {
+      return { ok: false, resolved: false, reason: `无可解决冲突: ${changeName}` };
+    }
+    return {
+      ok: outcomes.every((o) => o.ok),
+      resolved: outcomes.every((o) => o.resolved),
+      mode,
+      reason: outcomes.map((o) => o.reason).join('；'),
+    };
   }
 
   /**
@@ -921,15 +1112,22 @@ export class SyncManager {
     try { files = readdirSync(runtimeDir); }
     catch { return []; }
     const conflicts = [];
+    // HUB-08：同时扫描进度冲突（sync-conflict-*）与 spec 树冲突（spec-sync-conflict-*），
+    // type 字段供 status 展示与 resolve 分流
     for (const f of files) {
-      if (!f.startsWith('sync-conflict-') || !f.endsWith('.json')) continue;
+      let prefix = null;
+      if (f.startsWith('sync-conflict-') && f.endsWith('.json')) prefix = 'sync-conflict-';
+      else if (f.startsWith('spec-sync-conflict-') && f.endsWith('.json')) prefix = 'spec-sync-conflict-';
+      else continue;
+      const type = prefix === 'sync-conflict-' ? 'progress' : 'spec-tree';
       const filePath = join(runtimeDir, f);
       try {
         const cf = JSON.parse(readFileSync(filePath, 'utf8'));
         conflicts.push({
-          change: cf.change || f.replace(/^sync-conflict-/, '').replace(/\.json$/, ''),
+          change: cf.change || f.replace(/^spec-sync-conflict-|^sync-conflict-/, '').replace(/\.json$/, ''),
           created_at: cf.created_at || null,
           path: filePath,
+          type,
         });
       } catch {
         // 损坏文件跳过不崩（constraints：容错）
@@ -984,21 +1182,10 @@ export class SyncManager {
 // ── CLI 入口函数 ──
 
 /**
- * syncModule — sillyspec platform 子命令入口
- *
- * 用法:
- *   sillyspec platform connect <url> <token>
- *   sillyspec platform disconnect
- *   sillyspec platform sync [changeName]
- *   sillyspec platform sync-docs [changeName]
- *   sillyspec platform approval <changeName>
- *   sillyspec platform status
- *
- * @param {string[]} args — 子命令及参数
- * @param {string} cwd — 工作目录
- */
-/**
- * 便捷函数导出 — 供 index.js 和 run.js 直接调用
+ * 便捷函数导出 — 供 index.js 直接调用（platform 子命令分发生在 index.js case 'platform'）。
+ * HUB-10：原此处另有内嵌 syncModule(args) CLI 分发死代码（全仓零调用、参数形态/子命令面与
+ * index.js 实际分叉——位置参数 token、缺 pull/resolve/pointer、多余 approval/check-approval），
+ * 误导维护者改错地方，已删除。
  */
 export async function connect(url, token, cwd) {
   return new SyncManager(cwd).connect(url, token);
@@ -1008,8 +1195,8 @@ export async function disconnect(cwd) {
   return new SyncManager(cwd).disconnect();
 }
 
-export async function sync(changeName, cwd) {
-  return new SyncManager(cwd).sync(changeName);
+export async function sync(changeName, cwd, opts) {
+  return new SyncManager(cwd).sync(changeName, opts);
 }
 
 // manual=true：本导出对应 CLI platform sync-docs 手动命令（index.js platform 分支唯一调用方），
@@ -1054,11 +1241,12 @@ export function listConflictFiles(cwd) {
 // 清单为锚做全树 diff，与变更目录无关——triggerSync 对 quick 会话降级只调本函数，
 // 不走 sync()（后者第二道 existsSync 门会以「变更不存在」提前 return）。
 // 未连接平台 → {synced: 0} 静默（本地合法状态，与 syncSpecTree 内部口径一致）。
-export async function syncSpecTreeOnly(changeName, cwd) {
+export async function syncSpecTreeOnly(changeName, cwd, opts = {}) {
   const sm = new SyncManager(cwd);
   const platform = sm._getPlatform();
   if (!platform) return { synced: 0 };
-  return syncSpecTree(join(cwd, '.sillyspec'), platform, changeName);
+  // 树根与 sync() 内链式推送同源（BUG-01：平台模式必须锚 specRoot，防本地空树触发全量 delete）
+  return syncSpecTree(safePlatformSpecDir(cwd) || join(cwd, '.sillyspec'), platform, changeName, { signal: opts.signal });
 }
 
 // TBD-hub-api: approve/reject 端点路径与请求体以 SillyHub 仓库实际 API 为准；
@@ -1147,77 +1335,3 @@ export async function status(cwd) {
     console.log(`上次连接: ${st.lastSync || '未知'}`);
   }
 }
-
-/**
- * syncModule — sillyspec platform 子命令入口
- */
-export async function syncModule(args, cwd) {
-  const sm = new SyncManager(cwd);
-
-  const sub = args[0];
-
-  switch (sub) {
-    case 'connect': {
-      const url = args[1];
-      const token = args[2];
-      if (!url || !token) {
-        console.error('用法: sillyspec platform connect <url> <token>');
-        process.exit(1);
-      }
-      await sm.connect(url, token);
-      break;
-    }
-
-    case 'disconnect':
-      sm.disconnect();
-      break;
-
-    case 'sync': {
-      const changeName = args[1];
-      const result = await sm.sync(changeName);
-      if (result.errors.length > 0) {
-        console.log(`同步完成，${result.errors.length} 个错误`);
-      }
-      break;
-    }
-
-    case 'sync-docs':
-    case 'sync-documents': {
-      const changeName = args[1];
-      // manual=true：CLI 手动命令路径，四件套缺失打 warn（ql-20260818-008 措辞分级）
-      const result = await sm.syncDocuments(changeName, { manual: true });
-      if (result.errors.length > 0) {
-        console.log(`文档同步完成，${result.errors.length} 个错误`);
-      }
-      break;
-    }
-
-    case 'approval':
-    case 'check-approval': {
-      const changeName = args[1];
-      if (!changeName) {
-        console.error('用法: sillyspec platform approval <changeName>');
-        process.exit(1);
-      }
-      const approval = await sm.checkApproval(changeName);
-      console.log(`审批状态: ${approval.status}${approval.reason ? ` (${approval.reason})` : ''}`);
-      break;
-    }
-
-    case 'status': {
-      const st = sm.status();
-      if (!st.connected) {
-        console.log('平台: 未连接');
-      } else {
-        console.log(`平台: ${st.url}`);
-        console.log(`上次连接: ${st.lastSync || '未知'}`);
-      }
-      break;
-    }
-
-    default:
-      console.error(`未知子命令: ${sub || '(无)'}`);
-      console.error('可用命令: connect, disconnect, sync, sync-docs, approval, status');
-      process.exit(1);
-  }
-}