sillyspec 3.27.6 → 3.27.7

package/.worktrees/2c37b1d7/src/sync.js

@@ -0,0 +1,1470 @@
+/**
+ * SillySpec SyncManager — SillyHub 平台同步模块
+ *
+ * 独立于 ProgressManager，由 run.js 和 index.js 调用。
+ * Best effort：所有网络失败 console.warn，不抛错，不阻塞主流程。
+ *
+ * 配置来源：.sillyspec/local.yaml 中的 platform 段
+ * HTTP 请求：Node.js 原生 fetch（Node 22+）
+ */
+
+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';
+import { openDatabase } from './db-engine.js';
+import { PLATFORM_MANAGED_FILENAME } from './run/shared.js';
+import { syncSpecTree } from './spec-sync.js';
+
+// sync 是 best-effort（网络失败只 warn）：平台指针失效时不抛，跳过平台、回退本地。
+function safePlatformSpecDir(cwd) {
+  try {
+    return resolvePlatformSpecDir(cwd);
+  } catch (e) {
+    console.warn(`[sync] 平台指针不可用，跳过平台同步：${String(e.message).split('\n')[0]}`);
+    return undefined;
+  }
+}
+
+const LOCAL_YAML = '.sillyspec/local.yaml';
+const CHANGES_DIR = '.sillyspec/changes';
+const REQUEST_TIMEOUT_MS = 10_000;
+
+// 未连接平台是本地独立用户的合法默认状态。sync / checkApproval 由 run 流程在后台 best-effort
+// 触发（每步完成、execute 阶段启动）；syncDocuments 仅由手动 `sillyspec platform sync-docs`
+// 命令触发（index.js sync-docs 分支），run 流程不自动推文档。未连接时默认静默跳过——不每步
+// 催连平台制造噪音（本地用户根本不需要平台）。需要排查同步行为时设 SILLYSPEC_DEBUG_SYNC=1。
+function debugLog(msg) {
+  if (process.env.SILLYSPEC_DEBUG_SYNC) console.warn(msg)
+}
+
+/** 四件套文档文件名 */
+const DOCUMENT_FILES = ['proposal.md', 'design.md', 'requirements.md', 'tasks.md'];
+
+// ── YAML 辅助 ──
+
+/**
+ * 简易 YAML 读取（解析为扁平 obj），供 _getPlatform / status 只读用。
+ * 与 worktree-guard.js 的 parseSimpleYaml 保持一致的轻量风格。
+ *
+ * 写入侧（connect/disconnect）**不再**走 parse→modify→write 有损往返——
+ * readLocalYaml/parseSimpleYaml 丢注释（:85 跳 # 行）、丢数组/深嵌套（只认一层 key:value），
+ * round-trip 会清空用户手填的注释与其他段。改为 readLocalYamlRaw + replaceTopLevelSection
+ * 文本级定向替换 platform 段，原文件注释/空行/其他段/数组/深嵌套/CRLF 字节级保留。
+ */
+function readLocalYaml(cwd) {
+  const p = join(cwd, LOCAL_YAML);
+  if (!existsSync(p)) return {};
+  try {
+    return parseSimpleYaml(readFileSync(p, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+/** 读 local.yaml 原始文本（保留注释/换行/结构），不存在返回 ''。供 connect/disconnect 文本级改写。 */
+function readLocalYamlRaw(cwd) {
+  const p = join(cwd, LOCAL_YAML);
+  if (!existsSync(p)) return '';
+  try {
+    return readFileSync(p, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * 定位顶层 YAML 段（如 platform:/mcp:）的行范围 [start, end)。
+ * 段 = key 行（行首非空白 + 以 'name:' 开头）+ 后续连续缩进行（以空格/tab 开头）。
+ * 遇空行/注释/下一个顶层 key 即段结束——这些行不属于本段，保留不动。
+ * split('\n')/join('\n') 操作：CRLF 下 '\r' 留在行尾，重组原样还原（Windows 兼容，CLAUDE.md #13）。
+ * @param {string} text
+ * @param {string} name - 段名（不含冒号，如 'platform'）
+ * @returns {{start: number, end: number} | null} 不存在返回 null
+ */
+function findTopLevelSectionRange(text, name) {
+  const lines = text.split('\n');
+  const prefix = `${name}:`;
+  let start = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    // 顶层 key 行：行首非空白（排除缩进子段）+ 以 'name:' 开头
+    if (/^\S/.test(line) && line.startsWith(prefix)) {
+      start = i;
+      break;
+    }
+  }
+  if (start === -1) return null;
+  let end = start + 1;
+  while (end < lines.length && /^[ \t]/.test(lines[end])) {
+    end++;
+  }
+  return { start, end };
+}
+
+/**
+ * 文本级定向替换/删除/追加一个顶层 YAML 段，保留文件其余所有字节
+ * （注释/空行/其他段/数组/深嵌套/CRLF 全保留）。
+ * @param {string} text - 原始文件文本
+ * @param {string} name - 段名（不含冒号）
+ * @param {string|null} body - 段体（不含 key 行）；null=删除该段；string=替换或追加
+ * @returns {string} 新文本
+ */
+function replaceTopLevelSection(text, name, body) {
+  const lines = text.split('\n');
+  const range = findTopLevelSectionRange(text, name);
+  if (range) {
+    const before = lines.slice(0, range.start);
+    const after = lines.slice(range.end);
+    if (body === null) {
+      return [...before, ...after].join('\n');
+    }
+    const sectionLines = [`${name}:`, ...body.split('\n')];
+    return [...before, ...sectionLines, ...after].join('\n');
+  }
+  // 段不存在
+  if (body === null) return text; // 删不存在的段，原样返回
+  // 追加：去尾换行后加空行分隔 + 新段；空文件直接起段
+  const stripped = text.replace(/(\r?\n)+$/, '');
+  if (stripped === '') {
+    return `${name}:\n${body}\n`;
+  }
+  return `${stripped}\n\n${name}:\n${body}\n`;
+}
+
+/** 文本级写 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 });
+  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) {
+  // 剥 YAML 双/单引号包裹（connect 写侧 yamlStr 加引号防 # : 注入，读侧对称剥；无引号值零影响）
+  const unquote = (v) => {
+    if (v.length >= 2 && ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'")))) {
+      return v.slice(1, -1);
+    }
+    return v;
+  };
+  const result = {};
+  let currentSection = null;
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    // 用原始 line（非 trimmed）判断缩进：trimmed 已去前导空格，startsWith(' ') 恒 false
+    // 会导致缩进子段（如 platform 下 url/token）被误判为 root 行、section 恒为空 {}
+    if (!line.startsWith(' ')) {
+      const m = trimmed.match(/^(\S+)\s*:\s*(.*)$/);
+      if (m) {
+        const key = m[1];
+        const val = unquote(m[2].trim());
+        if (val) {
+          result[key] = val;
+          currentSection = null;
+        } else {
+          result[key] = {};
+          currentSection = key;
+        }
+      }
+    } else if (currentSection) {
+      const m = trimmed.match(/^(\S+)\s*:\s*(.*)$/);
+      if (m && result[currentSection] && typeof result[currentSection] === 'object') {
+        result[currentSection][m[1]] = unquote(m[2].trim());
+      }
+    }
+  }
+  return result;
+}
+
+/**
+ * 解析推送者身份（user）：区分多用户，供 push 时 X-SillySpec-User 标识（design D-004）。
+ * 优先级：显式参数 > git user.name（与 quicklog / prompt <git-user> 同口径）> process.env.USER
+ * （Unix）/ USERNAME（Windows）。Best effort：全失败返回 null，调用方据此决定是否写 user 字段
+ * （缺字段等价于「未知推送者」，平台侧自行兜底，不报错）。
+ */
+function resolvePlatformUser(cwd, explicitUser) {
+  if (typeof explicitUser === 'string' && explicitUser.trim()) {
+    return explicitUser.trim();
+  }
+  // 回退 1：git user.name（safeGit 失败返回 null，不抛）
+  const gitUser = safeGit(cwd, ['config', 'user.name']).value;
+  if (gitUser) return gitUser;
+  // 回退 2：环境变量（USER=Unix / USERNAME=Windows；跨平台兼容 CLAUDE.md #13）
+  return process.env.USER || process.env.USERNAME || null;
+}
+
+// ── 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 signal = combineSignals(options.signal);
+  try {
+    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)}`);
+      return null;
+    }
+    const ct = res.headers.get('content-type') || '';
+    if (ct.includes('application/json')) {
+      return res.json();
+    }
+    return null;
+  } catch (err) {
+    if (err.name === 'AbortError') {
+      console.warn(`[sync] ${url} 请求超时/中断 (${REQUEST_TIMEOUT_MS}ms 上限或外部熔断)`);
+    } else {
+      console.warn(`[sync] ${url} 请求失败: ${err.message}`);
+    }
+    return null;
+  }
+}
+
+/**
+ * 带状态码的 fetch：不吞非 2xx（fetchJson 在 !res.ok 时返回 null 丢状态，无法区分 409 冲突）。
+ * 返回 { ok, status, body }：body 尽力 JSON.parse（平台冲突响应带 progress JSON，读回给调用方）。
+ * 仅 sync() 的 progress POST 使用（识别 base_ts 乐观锁冲突，D-015 / task-09）；其余调用仍走 fetchJson。
+ */
+async function fetchJsonWithStatus(url, options = {}) {
+  const signal = combineSignals(options.signal);
+  try {
+    const res = await fetch(url, { ...options, signal });
+    const text = await res.text().catch(() => '');
+    let body = null;
+    if (text) {
+      try { body = JSON.parse(text); } catch { body = null; }
+    }
+    if (!res.ok) {
+      console.warn(`[sync] ${options.method || 'GET'} ${url} → ${res.status} ${text.slice(0, 200)}`);
+    }
+    return { ok: res.ok, status: res.status, body };
+  } catch (err) {
+    if (err.name === 'AbortError') {
+      console.warn(`[sync] ${url} 请求超时/中断 (${REQUEST_TIMEOUT_MS}ms 上限或外部熔断)`);
+    } else {
+      console.warn(`[sync] ${url} 请求失败: ${err.message}`);
+    }
+    return { ok: false, status: 0, body: null };
+  }
+}
+
+// ── SyncManager ──
+
+export class SyncManager {
+  constructor(cwd) {
+    this.cwd = cwd;
+    // 归档尾声静默化旗标（坑 post-archive-sync-noise）：sync() 探测到已归档时置位，
+    // 链内 syncDocuments 的「变更不存在」降 debug（每次 sync 调用重置）
+    this._suppressDocsMissingWarn = false;
+  }
+
+  /**
+   * 连接 SillyHub 平台。
+   * 保存配置到 .sillyspec/local.yaml，发送 ping 验证连接。
+   * @param {string} url - 平台地址
+   * @param {string} token - 认证 token
+   * @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) {
+      console.warn(`[sync] 平台连接验证失败: ${url}`);
+      return;
+    }
+    console.log(`[sync] 平台连接成功: ${url}`);
+
+    // 换发 workspace-scoped 同步 token（task-09 / D-005@v1）：用传入 user 级 token
+    // （shk_live_ / JWT）作 Bearer + 本地 root_path（connect 的 cwd，与平台
+    // Workspace.root_path 绑定值等值匹配）调 resolve-by-root-path。成功取 shpsync_
+    // 覆盖 token 写入 platform 段；404（root_path 未绑）/403（无 WORKSPACE_WRITE）/断网
+    // 均降级沿用原 token 继续（best-effort 不阻断 connect）。
+    let effectiveToken = token;
+    const resolveUrl = `${normalizedUrl}/api/workspaces/resolve-by-root-path`;
+    const resolved = await fetchJson(resolveUrl, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ root_path: this.cwd }),
+    });
+    if (resolved && resolved.token && resolved.token.startsWith('shpsync_')) {
+      effectiveToken = resolved.token;
+      console.log(
+        `[sync] 已换发 workspace-scoped 同步 token (workspace: ${resolved.workspace_id})`
+      );
+    } else {
+      console.warn(
+        '[sync] 换发 workspace-scoped token 失败（404/403/断网），沿用原 token 继续'
+      );
+    }
+
+    // 解析推送者身份（D-004）：显式 > git user.name > env；全失败留空不写 user 字段
+    const resolvedUser = resolvePlatformUser(this.cwd, user);
+
+    // 文本级改写 local.yaml：定向替换 platform 段，原文件注释/其他段/数组/深嵌套/CRLF 字节级保留
+    // （旧 read-modify-write 经 parseSimpleYaml 丢注释+丢非扁平结构，round-trip 清空用户手填内容）。
+    // YAML 值加引号：token/url 含 # : 或首尾空白时裸写会破坏段结构或注入额外键（shpsync_ token
+    // 当前不含这些字符，防御性包裹零成本；parseSimpleYaml 读侧剥引号兼容）
+    const yamlStr = (v) => JSON.stringify(String(v));
+    const platformEntries = [
+      `  url: ${yamlStr(normalizedUrl)}`,
+      `  token: ${yamlStr(effectiveToken)}`,
+      `  last_connected: ${yamlStr(new Date().toISOString())}`,
+    ];
+    if (resolvedUser) {
+      platformEntries.push(`  user: ${yamlStr(resolvedUser)}`);
+    }
+    let text = readLocalYamlRaw(this.cwd);
+    text = replaceTopLevelSection(text, 'platform', platformEntries.join('\n'));
+    // mcp 段同源假设（design §7.4）：url 复用 platform 的 url；token 用原始 user 级 token
+    // （非换发的 effectiveToken——MCP 派发需 user 级权限，platform 段才是最小权限的 shpsync_）。
+    // 用户已手填 mcp 段则保留不覆盖（R-09，文本级检测）
+    if (findTopLevelSectionRange(text, 'mcp') === null) {
+      text = replaceTopLevelSection(text, 'mcp', `  url: ${yamlStr(normalizedUrl)}\n  token: ${yamlStr(token)}`);
+    }
+    writeLocalYamlRaw(this.cwd, text);
+  }
+
+  /**
+   * 断开平台连接（三清，D-C@v2）。
+   * 1. 从 local.yaml 删除 platform 配置段；
+   * 2. 删恢复指针 <cwd>/.sillyspec-platform.json；
+   * 3. 删平台接管声明 <cwd>/.sillyspec-platform-managed。
+   * 不删后两者则"disconnect 后恢复本地模式"不可达（指针健在时 resolvePlatformSpecDir
+   * 仍解析平台 specRoot；声明健在时指针缺失会 fail-closed）。
+   */
+  disconnect() {
+    const p = join(this.cwd, LOCAL_YAML);
+    if (existsSync(p)) {
+      const text = readFileSync(p, 'utf8');
+      if (findTopLevelSectionRange(text, 'platform') !== null) {
+        // 文本级删除 platform 段，保留注释/其他段/数组/深嵌套/CRLF
+        const newText = replaceTopLevelSection(text, 'platform', null);
+        if (newText.trim() === '') {
+          // 删段后纯空白（无任何段也无注释）→ 删除整个文件；注释算内容，有注释则保留
+          try { unlinkSync(p); } catch { /* best effort */ }
+        } else {
+          writeAtomicSync(p, newText, 'utf8');
+        }
+      }
+    }
+    // 三清之二/三：指针 + 接管声明（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);
+      if (existsSync(fp)) {
+        try { unlinkSync(fp); cleaned.push(f); } catch { /* best effort */ }
+      }
+    }
+    if (cleaned.length > 0) console.log(`[sync] 已清理平台指针与接管声明: ${cleaned.join(', ')}`);
+    console.log('[sync] 已断开连接');
+  }
+
+  /**
+   * 增量同步变更的 progress 状态到平台。
+   * 读取 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, opts = {}) {
+    const { fromResolve = false } = opts;
+    const platform = this._getPlatform();
+    if (!platform) {
+      debugLog('[sync] 未连接平台（本地合法状态）；如需平台同步：sillyspec platform connect');
+      return { synced: 0, errors: ['未连接平台'] };
+    }
+
+    if (!changeName) {
+      console.warn('[sync] sync 需要指定变更名称 (changeName)');
+      return { synced: 0, errors: ['未指定变更名称'] };
+    }
+
+    // 冲突降噪（坑 sync-conflict-banner-spam，2026-08-23 实证：push 冲突落 sync-conflict 文件后，
+    // 每步完成的 triggerSync 都会再 push 再 409 再打全幅双线横幅——「已卡死不会自愈」连环刷屏，
+    // 观感像致命错误。冲突文件本身就代表「待人工三选一的未决状态」，文件在 = 用户已被告知，
+    // 后续自动同步单行提示即可（可见但不吓人）；resolve 后文件删除，推送自动恢复。fromResolve
+    // （keep-local 自动重推）不在此列——resolve 流程刚删冲突文件，它需要真实 push 判定平台态。
+    if (!fromResolve) {
+      const pendingConflict = this.readConflictFile(changeName);
+      if (pendingConflict) {
+        console.warn(`⚠️ [sync] 变更 ${changeName} 存在未决平台冲突，跳过自动推送。处理：sillyspec platform resolve ${changeName} --keep-local | --take-platform | --abort`);
+        return { synced: 0, errors: [`conflict pending: ${changeName}`], conflict: true, suppressed: true };
+      }
+    }
+
+    // 检查变更目录是否存在（归档后目录已移走但 DB 仍有最终状态需推平台，serializeForSync 从
+    // DB 读不依赖文件系统目录）。归档终态探测（坑 post-archive-sync-noise，2026-08-21 实证：
+    // 归档尾声连打「目录不存在/变更不存在」warn，观感像出错）：确认已归档（changes/archive/
+    // 有实体 或 DB status='archived'）时降为一行 info 措辞——正常时序不是告警。
+    const changeDir = join(this.cwd, CHANGES_DIR, changeName);
+    let archivedQuietly = false;
+    if (!existsSync(changeDir)) {
+      archivedQuietly = existsSync(join(this.cwd, CHANGES_DIR, 'archive', changeName))
+        || this._isChangeArchivedInDb(changeName);
+      if (archivedQuietly) {
+        console.log(`[sync] 变更已归档（目录在 archive/），继续从 DB 推送最终状态: ${changeName}`);
+      } else {
+        console.warn(`[sync] 变更目录不存在（可能是已归档，继续从 DB 同步最终状态）: ${changeName}`);
+      }
+    }
+    // 透传给本次 sync 链内的 syncDocuments（best-effort 四件套直推：归档后目录已移走，
+    // 其「变更不存在」warn 属正常时序，静默化）
+    this._suppressDocsMissingWarn = archivedQuietly;
+
+    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),
+        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));
+            }
+          }
+        }
+
+        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: [] };
+      }
+
+      if (res.status !== 409) {
+        return { synced: 0, errors: [`同步请求失败: ${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;
+      }
+
+      // push 侧内容一致自愈（坑 push-409-foreign-noise，2026-08-23 实证：他机/部署重推了内容
+      // 相同的进度——pull 侧已有 _progressContentEquals 自愈（坑 pull-deploy-noise-conflict），
+      // push 409 路径没有：外来噪声形态落真冲突 + 横幅 + 人工 resolve，而内容其实零分歧）。
+      // 409 回执的 platform_progress 与本次待推内容过同一比对（忽略时间戳列），一致 → 平台
+      // 「更新」只是噪声重推，本地无可丢失 → 跳过本次推送 + base_ts 推进到平台 ts（与
+      // resolve --keep-local 同语义，自动闭环），不落冲突文件。内容不同 → 真分歧，维持原判。
+      try {
+        if (platformProgress && this._progressContentEquals(progressData, platformProgress)) {
+          try {
+            const { ProgressManager } = await import('./progress.js');
+            const pm = new ProgressManager({ specDir: safePlatformSpecDir(this.cwd) });
+            pm._ensureDB(this.cwd).getDb().prepare(
+              'UPDATE changes SET last_synced_platform_ts = MAX(?, COALESCE(last_synced_platform_ts, ?)) WHERE name = ?'
+            ).run(platformLastPushedAt || pushedAt, platformLastPushedAt || pushedAt, changeName);
+          } catch {}
+          console.warn(`⚠️ [sync] push 409 内容一致自愈: 平台 ts=${platformLastPushedAt} 为外来噪声重推（六表内容与本地一致），base_ts 已推进，不落冲突文件`);
+          return { synced: 1, errors: [], selfHealed: true, reason: 'push 409 平台内容与本地一致（外来噪声重推），base_ts 已推进' };
+        }
+      } catch { /* 比对失败维持原判（fail-closed 到真冲突分支） */ }
+
+      // 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 };
+    }
+
+    // 循环耗尽（自愈重试后仍 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 {
+      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 到真冲突分支）
+    }
+  }
+
+  /**
+   * 同步四件套文档到平台（全量同步）。
+   * POST {url}/api/changes/{changeName}/documents
+   * @param {string} changeName
+   * @param {{manual?: boolean}} [opts] - manual=true 手动 sync-docs 命令路径（四件套缺失打 warn）；
+   *   默认自动路径（sync() 顺带推）四件套缺失是流程早期正常状态，降 debug 不噪音（ql-20260818-008）
+   */
+  async syncDocuments(changeName, opts = {}) {
+    const { manual = false } = opts;
+    const platform = this._getPlatform();
+    if (!platform) {
+      debugLog('[sync] 未连接平台（本地合法状态）；如需平台同步：sillyspec platform connect');
+      return { synced: 0, errors: ['未连接平台'] };
+    }
+
+    if (!changeName) {
+      console.warn('[sync] syncDocuments 需要指定变更名称 (changeName)');
+      return { synced: 0, errors: ['未指定变更名称'] };
+    }
+
+    // 树根与进度/spec 树同源（safePlatformSpecDir，BUG-01 同族）：此前硬编码 cwd/.sillyspec/changes，
+    // 平台模式（specRoot 指向外部）下路径不存在 → syncDocuments 恒报「变更不存在」且调用方不查
+    // 返回值 → 文档在平台模式下静默永不同步。
+    const changeDir = join(safePlatformSpecDir(this.cwd) || join(this.cwd, '.sillyspec'), 'changes', changeName);
+    if (!existsSync(changeDir)) {
+      // 归档尾声静默化（坑 post-archive-sync-noise）：sync() 链内调用（_suppressDocsMissingWarn
+      // 置位，目录已移 archive/ 的正常时序）降为 debug；独立调用（手动 sync-docs）保留 warn
+      if (this._suppressDocsMissingWarn) {
+        debugLog(`[sync] 四件套目录不存在（变更已归档，跳过文档直推）: ${changeName}`);
+        return { synced: 0, errors: [] };
+      }
+      console.warn(`[sync] 变更不存在: ${changeName}`);
+      return { synced: 0, errors: [`变更不存在: ${changeName}`] };
+    }
+
+    const documents = {};
+    let syncedCount = 0;
+    const errors = [];
+
+    for (const docFile of DOCUMENT_FILES) {
+      const docPath = join(changeDir, docFile);
+      if (existsSync(docPath)) {
+        try {
+          documents[docFile] = readFileSync(docPath, 'utf8');
+          syncedCount++;
+        } catch (err) {
+          errors.push(`读取 ${docFile} 失败: ${err.message}`);
+        }
+      }
+    }
+
+    if (syncedCount === 0) {
+      // ql-20260818-008：四件套缺失在流程早期是正常状态（brainstorm 中途 design/proposal 还没写），
+      // 自动路径降 debug——原 warn「未找到可同步的文档」不说只找四件套，曾让用户误判同步逻辑错了；
+      // 手动 platform sync-docs 是显式意图，保留 warn 但说清范围。
+      if (manual) {
+        console.warn(`[sync] 未找到可同步的四件套文档（proposal/design/requirements/tasks.md）: ${changeName}`);
+      } else {
+        debugLog(`[sync] 四件套尚未生成，跳过文档直推: ${changeName}`);
+      }
+      return { synced: 0, errors: [...errors, '无可用文档'] };
+    }
+
+    const docUrl = `${platform.url}/api/changes/${encodeURIComponent(changeName)}/documents`;
+    const result = await fetchJson(docUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${platform.token}`,
+      },
+      body: JSON.stringify(documents),
+      signal: opts.signal, // HUB-09：熔断 abort 传到底层请求
+    });
+
+    if (!result) {
+      return { synced: 0, errors: [...errors, '文档同步请求失败'] };
+    }
+
+    console.log(`[sync] 已同步 ${syncedCount} 个文档: ${changeName}`);
+    return { synced: syncedCount, errors };
+  }
+
+  /**
+   * 检查变更的审批状态。
+   * GET {url}/api/changes/{changeName}/approval
+   * 返回 { status: 'pending'|'approved'|'rejected', reason?: string }
+   */
+  async checkApproval(changeName) {
+    const platform = this._getPlatform();
+    if (!platform) {
+      debugLog('[sync] 未连接平台（本地合法状态）；如需平台同步：sillyspec platform connect');
+      return { status: 'pending', reason: '未连接平台' };
+    }
+
+    if (!changeName) {
+      console.warn('[sync] checkApproval 需要指定变更名称 (changeName)');
+      return { status: 'pending', reason: '未指定变更名称' };
+    }
+
+    const approvalUrl = `${platform.url}/api/changes/${encodeURIComponent(changeName)}/approval`;
+    const result = await fetchJson(approvalUrl, {
+      headers: { Authorization: `Bearer ${platform.token}` },
+    });
+
+    if (!result) {
+      console.warn(`[sync] 检查审批状态失败: ${changeName}`);
+      return { status: 'unknown', reason: '请求失败（404/断网/超时），无法核实审批状态' };
+    }
+
+    // 更新本地 approvals 表
+    try {
+      const { ProgressManager } = await import('./progress.js');
+      const pm = new ProgressManager({ specDir: safePlatformSpecDir(this.cwd) });
+      pm._updateApprovalStatus(this.cwd, changeName, result.status, result.reason);
+    } catch (err) {
+      console.warn(`[sync] 更新本地审批状态失败: ${err.message}`);
+    }
+
+    if (result.status === 'rejected') {
+      console.warn(`[sync] 审批被拒绝 (${changeName}): ${result.reason || '无原因'}`);
+    }
+
+    return result;
+  }
+
+  /**
+   * 查看同步状态。
+   * 读取 local.yaml 中的 platform 配置，返回连接信息。
+   */
+  status() {
+    const config = readLocalYaml(this.cwd);
+    const platform = config.platform;
+    if (!platform) {
+      return { connected: false };
+    }
+    return {
+      connected: true,
+      url: platform.url,
+      lastSync: platform.last_connected || null,
+    };
+  }
+
+  /** 获取当前平台配置，未连接返回 null */
+  _getPlatform() {
+    const config = readLocalYaml(this.cwd);
+    return config.platform || null;
+  }
+
+  /**
+   * DB 侧归档态探测（坑 post-archive-sync-noise）：changes 表 status='archived' 即真。
+   * 只读直查（node:sqlite，不经 ProgressManager——sync 是短进程，惰性 import 无收益且
+   * 本调用点在同步代码段）；DB 不存在/无行/读失败 → false（保守退回普通 warn 措辞）。
+   * @param {string} changeName
+   * @returns {boolean}
+   */
+  _isChangeArchivedInDb(changeName) {
+    try {
+      const dbPath = join(safePlatformSpecDir(this.cwd) || join(this.cwd, '.sillyspec'), '.runtime', 'sillyspec.db');
+      if (!existsSync(dbPath)) return false;
+      const db = openDatabase(dbPath, { readOnly: true });
+      try {
+        const row = db.prepare("SELECT status FROM changes WHERE name = ?").get(changeName);
+        return row?.status === 'archived';
+      } finally { try { db.close() } catch {} }
+    } catch { return false }
+  }
+
+  /**
+   * 写冲突文件 .runtime/sync-conflict-<change>.json（task-12 / D-002 / D-008 / D-010 / FR-05）。
+   * push 409 与 pull 本地脏度双向冲突命中时调用，强制提示用户走 platform resolve 三选一。
+   * 绝不字段级 auto-merge；文件在 .runtime 下不入版本控制（gitignore）。
+   * @param {string} changeName
+   * @param {{base_ts?: string|null, local_modified_ts?: string|null, platform_last_pushed_at?: string|null, platform_progress?: object|null}} info
+   * @returns {string|null} 冲突文件路径（specDir 不可达返回 null）
+   */
+  /**
+   * 六表内容比对（坑 pull-deploy-noise-conflict 自愈用）：本地 serializeForSync 快照与平台
+   * 拉回的 JSON 逐表深度比对，忽略时间戳/同步元数据列（last_active/last_synced_platform_ts/
+   * last_local_modified_ts/started_at/completed_at/pushed_at/checked_at/completed_at 等——部署
+   * 噪声重推会刷新这些列但内容不变）。任一实质差异 → false。
+   * @param {object} local - serializeForSync 输出
+   * @param {object} platform - 平台 GET progress JSON（serializeForSync 同构）
+   * @returns {boolean}
+   */
+  _progressContentEquals(local, platform) {
+    try {
+      const IGNORE_KEYS = new Set([
+        'last_active', 'last_synced_platform_ts', 'last_local_modified_ts',
+        'started_at', 'completed_at', 'pushed_at', 'last_pushed_at', 'created_at',
+        'deps_checked_at', 'checked_at', 'waited_at', 'completedat',
+      ]);
+      const strip = (v) => {
+        if (Array.isArray(v)) return v.map(strip);
+        if (v && typeof v === 'object') {
+          const out = {};
+          // sort 必须按 key 字符串比较（坑 content-equals-sort-typeerror，2026-08-23 实证：
+          // 默认比较器把 [key, value] 元素转字符串，serializeForSync 输出的 project 字段是
+          // null-prototype 对象（不可转原始值）→ sort 抛 TypeError 被下方 catch 吞成恒 false
+          // ——pull/push 两侧内容一致自愈形同虚设，部署噪声全部落真冲突人工 resolve）。
+          const entries = Object.entries(v).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+          for (const [k, val] of entries) {
+            if (IGNORE_KEYS.has(k)) continue;
+            out[k] = strip(val);
+          }
+          return out;
+        }
+        return v;
+      };
+      return JSON.stringify(strip(local)) === JSON.stringify(strip(platform));
+    } catch { return false }
+  }
+
+  _writeConflictFile(changeName, info = {}) {
+    const specDir = safePlatformSpecDir(this.cwd);
+    if (!specDir) return null;
+    const runtimeDir = join(specDir, '.runtime');
+    if (!existsSync(runtimeDir)) mkdirSync(runtimeDir, { recursive: true });
+    const conflictPath = join(runtimeDir, `sync-conflict-${changeName}.json`);
+    const payload = {
+      change: changeName,
+      base_ts: info.base_ts ?? null,
+      local_modified_ts: info.local_modified_ts ?? null,
+      platform_last_pushed_at: info.platform_last_pushed_at ?? null,
+      created_at: new Date().toISOString(),
+      // 额外存平台最新 progress JSON，供 resolve --take-platform 直接 import（无需再 pull）
+      platform_progress: info.platform_progress ?? null,
+    };
+    writeFileSync(conflictPath, JSON.stringify(payload, null, 2) + '\n', 'utf8');
+    return conflictPath;
+  }
+
+  /**
+   * 读取冲突文件（task-13 resolve / task-14 status 用）。
+   * @returns {object|null} 冲突文件内容；无文件返回 null
+   */
+  readConflictFile(changeName) {
+    const specDir = safePlatformSpecDir(this.cwd);
+    if (!specDir) return null;
+    const conflictPath = join(specDir, '.runtime', `sync-conflict-${changeName}.json`);
+    if (!existsSync(conflictPath)) return null;
+    try {
+      return JSON.parse(readFileSync(conflictPath, 'utf8'));
+    } catch {
+      return null;
+    }
+  }
+
+  // ── 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）
+   */
+  clearConflictFile(changeName) {
+    const specDir = safePlatformSpecDir(this.cwd);
+    if (!specDir) return false;
+    const conflictPath = join(specDir, '.runtime', `sync-conflict-${changeName}.json`);
+    if (!existsSync(conflictPath)) return false;
+    try { unlinkSync(conflictPath); return true; }
+    catch { return false; }
+  }
+
+  /**
+   * 两级 pull 第一级：轻量 change 列表（design §7 / D-001 / D-006 / task-06 / FR-01 / FR-03）。
+   * GET {url}/api/changes → [{ name, current_stage, last_pushed_at, last_pusher }]（兼容 { changes: [...] } 包裹）。
+   * CLI 比对本地决定哪些 change 需更新，控制 pull 性能（不每次全量拉单 change JSON）。
+   * Best Effort：未连接 / 网络失败 console.warn 不抛，返回 PullListResult { ok, changes, reason? }。
+   * @returns {Promise<{ok: boolean, changes: Array<object>, reason?: string}>}
+   */
+  async pullList() {
+    const platform = this._getPlatform();
+    if (!platform) {
+      debugLog('[sync] 未连接平台（本地合法状态）；pullList 跳过');
+      return { ok: false, changes: [], reason: '未连接平台' };
+    }
+
+    const listUrl = `${platform.url}/api/changes`;
+    const result = await fetchJson(listUrl, {
+      headers: { Authorization: `Bearer ${platform.token}` },
+    });
+
+    if (result === null) {
+      console.warn(`[sync] 拉取变更列表失败: ${listUrl}`);
+      return { ok: false, changes: [], reason: '拉取变更列表失败' };
+    }
+
+    // 兼容两种响应形态：裸数组 / { changes: [...] } 包裹（sillyhub 后端实际 API 而定）
+    const changes = Array.isArray(result) ? result : (Array.isArray(result.changes) ? result.changes : []);
+    return { ok: true, changes, reason: undefined };
+  }
+
+  /**
+   * 两级 pull 第二级：按需拉平台单 change 完整 JSON 并 import 重建本地 DB 行（design §7 / D-001 / D-006 / D-014 / task-07 / FR-01 / FR-03 / FR-09）。
+   * GET {url}/api/changes/{name}/progress → 平台权威 JSON（serializeForSync 六表 + 顶层 last_pushed_at）。
+   * 本地脏度比对：last_local_modified_ts > last_synced_platform_ts（本地有未同步改动）且 平台 last_pushed_at 更新 → 冲突，不 import 返回 conflict:true（task-12 负责写 sync-conflict 文件）。
+   * 无冲突 → import() 重建 DB 行；import 后本地 base_ts/脏度重置为 pushed_at（D-013）。
+   * Best Effort：未连接 / 网络失败 / 404 console.warn 不抛，返回 PullResult { ok, imported, conflict, reason? }。
+   * @param {string} changeName
+   * @param {{force?: boolean, skipIfLocalDirty?: boolean}} [opts] - force 跳过本地脏度冲突检测直接
+   *   import（task-12 resolve --take-platform 用）；skipIfLocalDirty 自动注入点（triggerPull/
+   *   triggerPullActiveChange）专用保守守卫——本地有未同步改动时跳过 import（ql-20260818-008）
+   * @returns {Promise<{ok: boolean, imported: boolean, conflict: boolean, reason?: string}>}
+   */
+  async pull(changeName, opts = {}) {
+    const { force = false, skipIfLocalDirty = false } = opts;
+    const platform = this._getPlatform();
+    if (!platform) {
+      debugLog('[sync] 未连接平台（本地合法状态）；pull 跳过');
+      return { ok: false, imported: false, conflict: false, reason: '未连接平台' };
+    }
+    if (!changeName) {
+      console.warn('[sync] pull 需要指定变更名称 (changeName)');
+      return { ok: false, imported: false, conflict: false, reason: '未指定变更名称' };
+    }
+
+    // 1. GET 平台完整 progress JSON
+    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 降级
+      console.warn(`[sync] 拉取变更进度失败: ${changeName}（sillyhub 未就绪或变更不存在）`);
+      return { ok: false, imported: false, conflict: false, reason: '拉取变更进度失败' };
+    }
+
+    // 平台响应：serializeForSync 六表 + 顶层 last_pushed_at（兼容 { progress: {...} } 包裹）
+    const platformProgress = (result && result.project && result.changes) ? result : (result.progress || result);
+    const platformPushedAt = (result && result.last_pushed_at) || null;
+
+    // 2. 本地脏度比对（非 force 时）：本地脏 AND 平台更新 → 冲突
+    if (!force) {
+      let localLastModified = null;
+      let localLastSynced = null;
+      try {
+        const { ProgressManager } = await import('./progress.js');
+        const pm = new ProgressManager({ specDir: safePlatformSpecDir(this.cwd) });
+        const row = pm._ensureDB(this.cwd).getDb().prepare(
+          'SELECT last_local_modified_ts, last_synced_platform_ts FROM changes WHERE name = ?'
+        ).get(changeName);
+        if (row) {
+          localLastModified = row.last_local_modified_ts;
+          localLastSynced = row.last_synced_platform_ts;
+        }
+      } catch (err) {
+        console.warn(`[sync] 读取本地脏度失败 (${changeName}): ${err.message}`);
+      }
+      let localDirty = localLastModified && localLastSynced && localLastModified > localLastSynced;
+      let platformNewer = platformPushedAt && (!localLastSynced || platformPushedAt > localLastSynced);
+      // 自竞态防御（坑 2026-08-19-platform-sync-base-ts-silent-conflict 改进点 3）：
+      // 判冲突用的 localLastSynced 若落后于本进程刚完成的 push 回填（另一连接 3ms 前推完、
+      // 本 pull 在其回填写库前读了旧值），会把自己刚写的 platformPushedAt 误判为「平台有更新」
+      // → 卡死。重读一次 DB：期间 push 回填已落库则 base_ts 已推进（>= platformPushedAt），
+      // platformNewer 翻 false，冲突自愈。重读仍旧则真冲突，维持原判。
+      if (localDirty && platformNewer) {
+        try {
+          const { ProgressManager } = await import('./progress.js');
+          const pm = new ProgressManager({ specDir: safePlatformSpecDir(this.cwd) });
+          const fresh = pm._ensureDB(this.cwd).getDb().prepare(
+            'SELECT last_synced_platform_ts FROM changes WHERE name = ?'
+          ).get(changeName);
+          if (fresh && fresh.last_synced_platform_ts) {
+            localLastSynced = fresh.last_synced_platform_ts;
+            platformNewer = platformPushedAt && platformPushedAt > localLastSynced;
+            if (!platformNewer) {
+              debugLog(`[sync] pull 自竞态解除: base_ts 已被本进程 push 回填推进到 ${localLastSynced}，平台 ts ${platformPushedAt} 非更新`);
+            }
+          }
+        } catch { /* 重读失败维持原判（fail-closed 到真冲突分支） */ }
+      }
+      // ── 内容一致自愈（坑 pull-deploy-noise-conflict，2026-08-22 实证：并行会话部署扰动——
+      // 他机 push 了内容相同的进度（如重启/重部署触发重推），本地脏 + 平台 ts 更新 → 拉冲突落
+      // sync-conflict 文件需人工 resolve，但内容其实无分歧。比对平台 JSON 与本地 serializeForSync
+      // 的六表内容（忽略时间戳列），一致 → 跳过 import（本地为准）+ base_ts 推进到平台 ts——
+      // 与 resolve --keep-local 同语义，自动闭环。内容不同 → 真冲突，维持原判。
+      if (localDirty && platformNewer && platformProgress) {
+        try {
+          const { ProgressManager } = await import('./progress.js');
+          const pm = new ProgressManager({ specDir: safePlatformSpecDir(this.cwd) });
+          const localSnapshot = pm.serializeForSync(this.cwd, changeName);
+          if (localSnapshot && this._progressContentEquals(localSnapshot, platformProgress)) {
+            try {
+              const db = pm._ensureDB(this.cwd).getDb();
+              db.prepare(
+                'UPDATE changes SET last_synced_platform_ts = MAX(?, COALESCE(last_synced_platform_ts, ?)) WHERE name = ?'
+              ).run(platformPushedAt, platformPushedAt, changeName);
+            } catch {}
+            debugLog(`[sync] pull 内容一致自愈: 平台 ts ${platformPushedAt} 为部署噪声重推（六表内容与本地一致），base_ts 已推进，不落冲突文件`);
+            return { ok: true, imported: false, conflict: false, reason: '平台重推内容与本地一致（部署噪声），base_ts 已推进' };
+          }
+        } catch { /* 比对失败维持原判（fail-closed 到真冲突分支） */ }
+      }
+      if (localDirty && platformNewer) {
+        console.warn('');
+        console.warn('⚠️⚠️⚠️════════════════════════════════════════════════════');
+        console.warn(`⚠️ 平台同步冲突：变更「${changeName}」pull 判定冲突（本地有未同步改动且平台已更新，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('⚠️⚠️⚠️════════════════════════════════════════════════════');
+        // 写冲突文件（task-12 / D-002）：强制提示，绝不 auto-merge
+        const conflictPath = this._writeConflictFile(changeName, {
+          base_ts: localLastSynced,
+          local_modified_ts: localLastModified,
+          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）保守守卫——本地有未同步
+      // 改动时跳过 import。原逻辑只拦「本地脏 且 平台更新」的真冲突，「本地领先」（本地脏、平台更旧）
+      // 仍会 import 平台旧快照覆盖本地新进度（数据丢失）。手动 platform pull 不传该 flag，语义不变。
+      if (skipIfLocalDirty && localDirty) {
+        debugLog(`[sync] pull 跳过（本地有未同步改动，防平台旧快照覆盖）: ${changeName}`);
+        return { ok: false, imported: false, conflict: false, reason: '本地有未同步改动，自动 pull 跳过' };
+      }
+    }
+
+    // 3. 无冲突（或 force）→ import 平台 JSON 重建本地 DB 行
+    try {
+      const { ProgressManager } = await import('./progress.js');
+      const pm = new ProgressManager({ specDir: safePlatformSpecDir(this.cwd) });
+      const importInput = { ...platformProgress, pushed_at: platformPushedAt || new Date().toISOString() };
+      pm.import(this.cwd, importInput, changeName);
+      console.log(`[sync] 已拉取变更进度: ${changeName}`);
+      return { ok: true, imported: true, conflict: false, reason: undefined };
+    } catch (err) {
+      console.warn(`[sync] import 失败 (${changeName}): ${err.message}`);
+      return { ok: false, imported: false, conflict: false, reason: `import 失败: ${err.message}` };
+    }
+  }
+
+  /**
+   * 冲突解决三选一（task-13 / D-002 / D-010 / D-013 / FR-05）。
+   * 读 task-12 写的 sync-conflict-<change>.json，按 mode 处理后必清冲突文件防累积（R-04 / constraints）。
+   *
+   * 三种语义（design 生命周期契约表）：
+   * - keep-local：本地 DB 不变，仅把 last_synced_platform_ts（base_ts）推进到平台 last_pushed_at
+   *   （表示「已知平台最新，本地为准」），用户后续手动 platform sync push 本地。
+   * - take-platform：用冲突文件存的 platform_progress 调 import() 覆盖本地（保隔离状态，D-013 重置脏度）。
+   * - abort：本地 DB 与 base_ts 均不变，仅清冲突文件（放弃本次同步）。
+   *
+   * 无冲突文件 → ok:false resolved:false（index.js 据此提示「无可解决冲突」）。
+   * 绝不字段级 auto-merge（D-002）。
+   * @param {string} changeName
+   * @param {'keep-local'|'take-platform'|'abort'} mode
+   * @returns {Promise<{ok: boolean, resolved: boolean, mode?: string, reason: string}>}
+   */
+  async resolve(changeName, mode) {
+    const cf = this.readConflictFile(changeName);
+    const specCf = this.readSpecConflictFile(changeName);
+    if (!cf && !specCf) {
+      return { ok: false, resolved: false, reason: `无可解决冲突: ${changeName}（无 sync-conflict / spec-sync-conflict 文件）` };
+    }
+    const platformPushedAt = (cf && cf.platform_last_pushed_at) || null;
+
+    // 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——无条件覆盖会把
+      // base_ts 拉回过去，下次 sync 立即撞 409 再落冲突文件（恢复时实测二轮才收敛）。
+      // COALESCE 防 NULL：SQLite 标量 MAX(x, NULL) 恒 NULL，首同步前 base_ts NULL 应直取平台 ts。
+      try {
+        const { ProgressManager } = await import('./progress.js');
+        const pm = new ProgressManager({ specDir: safePlatformSpecDir(this.cwd) });
+        const db = pm._ensureDB(this.cwd).getDb();
+        // 参数侧同样 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);
+      // 自动重推闭环（坑 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' && 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）' };
+      }
+      try {
+        const { ProgressManager } = await import('./progress.js');
+        const pm = new ProgressManager({ specDir: safePlatformSpecDir(this.cwd) });
+        pm.import(this.cwd, { ...cf.platform_progress, pushed_at: platformPushedAt || new Date().toISOString() }, changeName);
+      } catch (err) {
+        progressOutcome = { ok: false, resolved: false, reason: `take-platform import 失败: ${err.message}` };
+      }
+      if (progressOutcome === null) {
+        this.clearConflictFile(changeName);
+        progressOutcome = { ok: true, resolved: true, 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') {
+      if (cf) this.clearConflictFile(changeName);
+      if (specCf) this.clearSpecConflictFile(changeName);
+      return { ok: true, resolved: true, mode: 'abort', reason: '放弃本次同步，本地不变' };
+    }
+
+    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('；'),
+    };
+  }
+
+  /**
+   * 扫描 .runtime/sync-conflict-*.json 列出未决冲突（task-14 / D-002 / D-010 / FR-05）。
+   * 只读 + 容错：损坏文件跳过不崩（constraints）。供 collectStatus / platform status 展示。
+   * @returns {Array<{change: string, created_at: string|null, path: string}>}
+   */
+  listConflictFiles() {
+    const specDir = safePlatformSpecDir(this.cwd);
+    if (!specDir) return [];
+    const runtimeDir = join(specDir, '.runtime');
+    if (!existsSync(runtimeDir)) return [];
+    let files = [];
+    try { files = readdirSync(runtimeDir); }
+    catch { return []; }
+    const conflicts = [];
+    // HUB-08：同时扫描进度冲突（sync-conflict-*）与 spec 树冲突（spec-sync-conflict-*），
+    // type 字段供 status 展示与 resolve 分流
+    for (const f of files) {
+      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(/^spec-sync-conflict-|^sync-conflict-/, '').replace(/\.json$/, ''),
+          created_at: cf.created_at || null,
+          path: filePath,
+          type,
+        });
+      } catch {
+        // 损坏文件跳过不崩（constraints：容错）
+      }
+    }
+    return conflicts;
+  }
+
+  /**
+   * 扩展 status（task-14 / FR-05）：连接信息 + 落后标记 + 未决冲突列表。
+   * 只读展示，不修改任何进度（constraints）。未连接返回 base.status（connected:false，behind/conflicts 空）。
+   * 连接时调 pullList（轻量 GET）拿平台各 change last_pushed_at，比对本地 last_synced_platform_ts
+   * 标记本地可能落后；扫描 sync-conflict-*.json 列未决冲突。网络失败 listFailed=true 不崩。
+   * @returns {Promise<{connected: boolean, url?: string, lastSync?: string|null, behind: Array<object>, conflicts: Array<object>, listFailed: boolean}>}
+   */
+  async collectStatus() {
+    const base = this.status();
+    if (!base.connected) {
+      return { ...base, behind: [], conflicts: [], listFailed: false };
+    }
+    const behind = [];
+    let listFailed = false;
+    const list = await this.pullList();
+    if (list.ok) {
+      for (const ch of list.changes) {
+        const name = typeof ch === 'string' ? ch : ch.name;
+        if (!name) continue;
+        const platformPushedAt = (typeof ch === 'object' && (ch.last_pushed_at || ch.last_active)) || null;
+        if (!platformPushedAt) continue;
+        let localSynced = null;
+        try {
+          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(name);
+          if (row) localSynced = row.last_synced_platform_ts;
+        } catch {
+          // 本地无该 change 记录 / DB 不可达 → 不算落后，跳过
+        }
+        // 仅本地有同步基准（last_synced_platform_ts）且平台更新晚于本地 → 落后
+        if (localSynced && platformPushedAt > localSynced) {
+          behind.push({ name, local_synced: localSynced, platform_pushed_at: platformPushedAt });
+        }
+      }
+    } else {
+      listFailed = true;
+    }
+    const conflicts = this.listConflictFiles();
+    return { ...base, behind, conflicts, listFailed };
+  }
+}
+
+// ── CLI 入口函数 ──
+
+/**
+ * 便捷函数导出 — 供 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);
+}
+
+export async function disconnect(cwd) {
+  return new SyncManager(cwd).disconnect();
+}
+
+export async function sync(changeName, cwd, opts) {
+  return new SyncManager(cwd).sync(changeName, opts);
+}
+
+// manual=true：本导出对应 CLI platform sync-docs 手动命令（index.js platform 分支唯一调用方），
+// 四件套缺失打 warn；sync() 内的自动顺带推走 SyncManager 实例方法默认 auto（ql-20260818-008）
+export async function syncDocuments(changeName, cwd) {
+  return new SyncManager(cwd).syncDocuments(changeName, { manual: true });
+}
+
+export async function checkApproval(changeName, cwd) {
+  return new SyncManager(cwd).checkApproval(changeName);
+}
+
+// task-11 / D-006 / D-009 / FR-03：手动 pull 便捷导出（index.js platform pull 子命令用，
+// 与自动 triggerPull 共用 SyncManager.pull 实例方法，行为一致）
+export async function pull(changeName, opts, cwd) {
+  return new SyncManager(cwd).pull(changeName, opts);
+}
+
+// 两级 pull 第一级（轻量 change 列表），platform pull 无 --change 时先拉列表再按需 pull
+export async function pullList(cwd) {
+  return new SyncManager(cwd).pullList();
+}
+
+// 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);
+}
+
+// task-14 / FR-05：扩展 status（连接信息 + 落后标记 + 未决冲突列表），index.js platform status 用
+export async function collectStatus(cwd) {
+  return new SyncManager(cwd).collectStatus();
+}
+
+// 未决冲突文件列表便捷导出（index.js platform resolve 参数解析/报错兜底用，只读）
+export function listConflictFiles(cwd) {
+  return new SyncManager(cwd).listConflictFiles();
+}
+
+// ql-20260818-011：quick 会话专用 spec 树同步入口。quick-<hex8> 会话按设计无
+// changes/<name>/ 实体目录，progress/四件套上行对它是孤儿数据（平台变更中心按磁盘
+// change_key join 永不命中），但 spec 树增量（QUICKLOG/模块文档的上行通道）以服务器
+// 清单为锚做全树 diff，与变更目录无关——triggerSync 对 quick 会话降级只调本函数，
+// 不走 sync()（后者第二道 existsSync 门会以「变更不存在」提前 return）。
+// 未连接平台 → {synced: 0} 静默（本地合法状态，与 syncSpecTree 内部口径一致）。
+export async function syncSpecTreeOnly(changeName, cwd, opts = {}) {
+  const sm = new SyncManager(cwd);
+  const platform = sm._getPlatform();
+  if (!platform) return { synced: 0 };
+  // 树根与 sync() 内链式推送同源（BUG-01：平台模式必须锚 specRoot，防本地空树触发全量 delete）
+  return syncSpecTree(safePlatformSpecDir(cwd) || join(cwd, '.sillyspec'), platform, changeName, { signal: opts.signal });
+}
+
+// TBD-hub-api: approve/reject 端点路径与请求体以 SillyHub 仓库实际 API 为准；
+// 对齐时只改本函数（_submitApproval），无需动 approve/reject 入口。
+/**
+ * 向平台提交审批决定（approve/reject 共用）。
+ *
+ * 显式用户/daemon 动作：网络/平台失败必须可见（decisions.md D-006@v1）——
+ * 与 best-effort 的 sync 不同，此处失败打 error 并置 process.exitCode = 1。
+ *
+ * @param {string} cwd - 工作目录
+ * @param {string} changeName - 变更名称
+ * @param {'approved'|'rejected'} decision - 审批决定
+ * @param {string|null} reason - rejected 时的原因（approved 时忽略）
+ * @returns {Promise<boolean>} 是否成功
+ */
+async function _submitApproval(cwd, changeName, decision, reason = null) {
+  const sm = new SyncManager(cwd);
+  const platform = sm._getPlatform();
+  if (!platform) {
+    console.error('❌ 未连接平台，请先 sillyspec platform connect');
+    process.exitCode = 1;
+    return false;
+  }
+
+  if (!changeName) {
+    console.error('❌ 审批需要指定变更名称 (changeName)');
+    process.exitCode = 1;
+    return false;
+  }
+
+  // TBD-hub-api: 端点路径/body 以 SillyHub 实际 API 为准，对齐时只改此处
+  const approvalUrl = `${platform.url}/api/changes/${encodeURIComponent(changeName)}/approval`;
+  const body = decision === 'rejected'
+    ? { decision: 'rejected', reason }
+    : { decision: 'approved' };
+
+  const result = await fetchJson(approvalUrl, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${platform.token}`,
+    },
+    body: JSON.stringify(body),
+  });
+
+  // fetchJson 在非 2xx / 网络错 / 超时 / 非 JSON 时返回 null
+  if (result === null) {
+    console.error(`❌ 审批请求失败 (${changeName} → ${decision})，详情见上方 [sync] 警告`);
+    process.exitCode = 1;
+    return false;
+  }
+
+  // HTTP 成功后更新本地 approvals 表（HTTP 已成功是主要目标，落库失败只 warn 不阻断）
+  try {
+    const { ProgressManager } = await import('./progress.js');
+    const pm = new ProgressManager({ specDir: safePlatformSpecDir(cwd) });
+    pm._updateApprovalStatus(cwd, changeName, decision, reason);
+  } catch (err) {
+    console.warn(`[sync] 更新本地审批状态失败 (${changeName}): ${err.message}`);
+  }
+
+  if (decision === 'approved') {
+    console.log(`✅ 已批准变更 ${changeName}`);
+  } else {
+    console.log(`✅ 已拒绝变更 ${changeName}${reason ? `（原因: ${reason}）` : ''}`);
+  }
+  return true;
+}
+
+export async function approve(changeName, cwd) {
+  return _submitApproval(cwd, changeName, 'approved');
+}
+
+export async function reject(changeName, reason, cwd) {
+  return _submitApproval(cwd, changeName, 'rejected', reason);
+}
+
+export async function status(cwd) {
+  const sm = new SyncManager(cwd);
+  const st = sm.status();
+  if (!st.connected) {
+    console.log('平台: 未连接');
+  } else {
+    console.log(`平台: ${st.url}`);
+    console.log(`上次连接: ${st.lastSync || '未知'}`);
+  }
+}