sillyspec 3.29.3 → 3.29.5

package/src/init.js

@@ -5,6 +5,7 @@ import { checkbox, confirm, input } from '@inquirer/prompts';
 import { ProgressManager } from './progress.js';
 import chalk from 'chalk';
 import { getVersion } from './version.js';
+import { injectCommandCards } from './command-cards.js';
 import { gitQuiet } from './git-helper.js';
 import { renderExample } from './config-schema.js';
 // 向后兼容：getVersion 已抽到轻量 version.js（避免 index.js 为 --version 静态加载 init.js 的 inquirer 税），
@@ -76,10 +77,11 @@ function copyDirSync(src, dst) {
 
 
 
-const VALID_TOOLS = ['claude', 'cursor', 'openclaw', 'codex', 'gemini', 'opencode'];
+const VALID_TOOLS = ['claude', 'zcode', 'cursor', 'openclaw', 'codex', 'gemini', 'opencode'];
 
 const TOOL_LABELS = {
   claude: 'Claude Code',
+  zcode: 'ZCode',
   cursor: 'Cursor',
   openclaw: 'OpenClaw',
   codex: 'OpenAI Codex (通过 AGENTS.md)',
@@ -288,14 +290,17 @@ function isTTY() {
 
 // ── 核心安装逻辑 ──
 
-function doInstall(projectDir, tools, subprojects = [], specDir = null, options = {}) {
+async function doInstall(projectDir, tools, subprojects = [], specDir = null, options = {}) {
   // specDir: 规范目录（默认 projectDir/.sillyspec）
   // projectDir: 源码项目根目录（用于工具检测、指令注入、.gitignore）
   // options.noSkills: 跳过 skills 复制段（--no-skills；指令注入不受影响）
   // options.platformMode: 平台模式（cmdInit 收到 platformOpts 非空）——项目内 .sillyspec/
   //   通常只有 local.yaml（平台 init lease 写、含用户手调 mcp 段），任何清理都会丢失，整体跳过
-  const { noSkills = false, platformMode = false } = options;
+  const { noSkills = false, platformMode = false, forceCards = false } = options;
   const spec = specDir || join(projectDir, '.sillyspec');
+  // 命令卡工具面（2026-09-21-flow-command-cards）：仅 zcode/claude 有落点（D-003）；
+  // noSkills/platformMode 与 skills 同门跳过（Grill P2-4）
+  const cardTools = noSkills || platformMode ? [] : tools.filter((t) => t === 'zcode' || t === 'claude');
 
   // 外部 specDir 时清理旧版本残留的 cwd/.sillyspec/（防止源码污染）。
   // ⚠️ 必须保护真实资产：若本地 .sillyspec 含 changes/（非空）、projects/（非空）
@@ -443,11 +448,23 @@ function doInstall(projectDir, tools, subprojects = [], specDir = null, options
     }
   }
 
-  // 注入 AGENTS.md 完整指引（claude/codex 共用：版本感知幂等三态四分支 + 旧 ## SillySpec 段迁移）
-  if (tools.includes('claude') || tools.includes('codex')) {
+  // 注入 AGENTS.md 完整指引（claude/codex/zcode 共用：版本感知幂等三态四分支 + 旧 ## SillySpec 段迁移；
+  // zcode 2026-09-21-flow-command-cards FR-05 入面——AGENTS.md 是跨工具通用标准内容源）
+  if (tools.includes('claude') || tools.includes('codex') || tools.includes('zcode')) {
     injectAgentsInstructions(projectDir);
   }
 
+  // 流程命令卡注入（2026-09-21-flow-command-cards：zcode→.zcode/commands/sillyspec/、claude→.claude/commands/sillyspec/；
+  // 尾部锚行三态幂等。与 skills 复制同门：noSkills/platformMode 跳过（工具目录零污染语义，Grill P2-4）；
+  // 挂点在 noSkills return 之前——卡与 AGENTS.md 同批，早于 skills 复制不影响）
+  if (cardTools.length > 0) {
+    const cards = await injectCommandCards(projectDir, { tools: cardTools, force: forceCards, version: getVersion() });
+    for (const w of cards.warnings) console.warn(`    ⚠️ [命令卡] ${w}`);
+    if (cards.written.length + cards.updated.length > 0) {
+      console.log(chalk.green(`    ✓ 流程命令卡已${cards.written.length ? '生成' : '更新'} ${cards.written.length + cards.updated.length} 张 → ${cardTools.map((t) => (t === 'zcode' ? '.zcode' : '.claude') + '/commands/sillyspec/').join(' + ')}`));
+    }
+  }
+
   // 注入 CLAUDE.md 指针（claude 专属：@AGENTS.md 导入薄文件，须在 AGENTS.md 之后）
   if (tools.includes('claude')) {
     injectClaudePointer(projectDir);
@@ -546,7 +563,7 @@ function showSummary(version, tools, specDir) {
 // ── 主命令 ──
 
 export async function cmdInit(projectDir, options = {}) {
-  const { tool, tools: toolsOpt, interactive, specDir, noSkills = false, platformOpts = null } = options;
+  const { tool, tools: toolsOpt, interactive, specDir, noSkills = false, forceCards = false, platformOpts = null } = options;
   const version = getVersion();
   const resolvedSpecDir = specDir ? resolve(specDir) : null;
 
@@ -654,7 +671,7 @@ export async function cmdInit(projectDir, options = {}) {
     }
 
     console.log('');
-    await doInstall(projectDir, selectedTools, subprojects, resolvedSpecDir, { noSkills, platformMode: platformOpts != null });
+    await doInstall(projectDir, selectedTools, subprojects, resolvedSpecDir, { noSkills, forceCards, platformMode: platformOpts != null });
     writeInitPlatformPointer(projectDir, resolvedSpecDir, platformOpts);
     showSummary(version, selectedTools, resolvedSpecDir);
     return;
@@ -682,7 +699,7 @@ export async function cmdInit(projectDir, options = {}) {
     tools = detectTools(projectDir);
   }
 
-  await doInstall(projectDir, tools, [], resolvedSpecDir, { noSkills, platformMode: platformOpts != null });
+  await doInstall(projectDir, tools, [], resolvedSpecDir, { noSkills, forceCards, platformMode: platformOpts != null });
   writeInitPlatformPointer(projectDir, resolvedSpecDir, platformOpts);
 
   console.log('');

package/src/machine-interface.js

@@ -15,7 +15,7 @@
  * 仅依赖 Node 18+ 原生 API，零新增外部依赖。
  */
 
-import { existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { ProgressManager, resolveSpecDir } from './progress.js';
 import { resolveRuntimeRoot } from './run/shared.js';
@@ -25,7 +25,6 @@ import { runVerifyTestCheck } from './verify-postcheck.js';
 import { checkCode } from './diagnostic-codes.js';
 
 // ============ 退出码常量（D-004@v1）============
-
 export const EXIT_OK = 0;          // 核验通过（可含 warnings）
 export const EXIT_BLOCKED = 1;     // 事实性阻断（JSON 含 errors）
 export const EXIT_UNKNOWN = 2;     // 无法核验（用法错/变更不存在/环境错/内部异常）
@@ -295,8 +294,9 @@ export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot, s
         vtWarnings.push(`⚠️ verify-test SKIPPED — gate 未核验测试（${vt.reason || 'local.yaml 未配置 commands.test 或显式无测试'}）。本次 gate 结论不含测试客观核验，driver 不应据 exit 0 判定测试通过；integration-critical 变更应在 verify 阶段降级 FAIL`);
       }
       // known_failures 豁免披露：本次 PASS 含豁免，driver 应提示人工复核清单是否过宽
+      // （quick-E，2026-09-20 报告问题 E：提示原不带清单位置，复核要先翻一遍才找到——带路径）
       if (vt.exemptedCount > 0) {
-        vtWarnings.push(`⚠️ verify-test PASS 含 ${vt.exemptedCount} 个 known_failures 豁免（${vt.reason || ''}）；driver 应提示人工复核豁免清单是否过宽（避免误豁免本变更引入的真实失败）`);
+        vtWarnings.push(`⚠️ verify-test PASS 含 ${vt.exemptedCount} 个 known_failures 豁免（${vt.reason || ''}）；driver 应提示人工复核豁免清单是否过宽（避免误豁免本变更引入的真实失败）——清单位置：${join(specRoot, 'local.yaml')} 的 known_failures 键`);
       }
       // 全量 fallback 明示：跑了全量 commands.test 但非变更范围子集，失败可能含未变更
       // 模块的预存错误——driver 不应据 exit 0 判定本次变更范围已客观测试（见 3.24 verify 坑1）。
@@ -318,6 +318,64 @@ export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot, s
           fallbackReason: vt.fallbackReason ?? null,
         },
       });
+
+      // ── d2. verify-lint（parity 补齐，2026-09-21 R4-S-F 实证）──
+      // gate verify 原先只查 test 不查 lint，而 verify --done 的 lint 隔离快照门会拦——
+      // gate PASS / --done FAIL 两套口径并存，误导 agent 诊断 16 分钟（对撞会话 db 实证）。
+      // 本检查与 --done 同引擎（runVerifyLintCheck + triageLintOwnership 归属降档）；口径差异
+      // 永久明示：gate 在工作树直跑 lint，--done 在隔离快照（HEAD+归属文件 overlay）跑——
+      // 不一致时以 --done 为准。lint 未配置/不可跑 → informational，不阻断只读查询。
+      try {
+        const { runVerifyLintCheck, triageLintOwnership, resolveVerifyChangedFiles } = await import('./verify-postcheck.js');
+        const lc = runVerifyLintCheck({ cwd, specBase: specRoot });
+        if (lc.status === 'skipped') {
+          checks.push({
+            id: 'verify-lint',
+            code: checkCode('verify-lint'),
+            ok: true,
+            informational: true,
+            warnings: [`verify-lint SKIPPED — ${lc.reason || 'local.yaml 未配置 commands.lint'}；本次 gate 结论不含 lint 客观核验`],
+            data: { status: lc.status },
+          });
+        } else {
+          const lcWarnings = [
+            '口径说明：gate verify 的 lint 在工作树直跑；verify --done 的 lint 在隔离快照（HEAD+归属文件 overlay）跑——两口径不一致时以 --done 为准。',
+          ];
+          let ownership = null;
+          let lintOk = lc.status !== 'failed';
+          if (lc.status === 'failed') {
+            const changed = resolveVerifyChangedFiles(cwd, changeName, null, { specBase: specRoot }) || [];
+            ownership = triageLintOwnership({ failureFiles: lc.failureFiles || [], changeFiles: changed });
+            if (ownership.verdict === 'pre-existing') {
+              lintOk = true; // 存量债不拦只读查询（与 --done 的 advisory 降档同口径）
+              lcWarnings.push('lint 失败文件与本变更零交集（HEAD 存量债）→ 本 check 降档放行；--done 同口径 advisory，建议顺手清偿解锁全仓 lint 门。');
+            }
+          }
+          checks.push({
+            id: 'verify-lint',
+            code: checkCode('verify-lint'),
+            ok: lintOk,
+            errors: !lintOk ? [`lint 失败（工作树口径）: ${lc.reason || ''}`] : [],
+            warnings: lcWarnings,
+            data: {
+              status: lc.status,
+              exitCode: lc.exitCode,
+              durationMs: lc.durationMs,
+              ownership: ownership ? ownership.verdict : null,
+              overlap: ownership ? ownership.overlap : [],
+            },
+          });
+        }
+      } catch (e) {
+        checks.push({
+          id: 'verify-lint',
+          code: checkCode('verify-lint'),
+          ok: true,
+          informational: true,
+          warnings: [`verify-lint 检查装配失败（fail-open）: ${e && e.message ? e.message : e}`],
+          data: { status: 'error' },
+        });
+      }
     }
 
     // ── 综合结论：所有非 informational check 均 ok ──
@@ -667,3 +725,30 @@ export function runStatusOverview({ cwd, specBase } = {}) {
     return { envelope, exitCode: EXIT_UNKNOWN };
   }
 }
+
+// ============ gate 失败明细稳定路径落盘（quick-D，2026-09-20 报告问题 D）============
+
+/**
+ * `sillyspec gate <stage> --change <name>` 的失败信封落盘（稳定路径，每次覆盖）。
+ * 背景：gate 失败明细只在 stdout——宿主把长命令转后台截断输出后 ❌ 段落实际取不回
+ * （2026-09-20 实证：agent 靠推断绕 3 轮）。runGate 本体保持只读契约（D-002@v1，不写
+ * sillyspec.db），落盘由本函数承担（CLI 层调用，fail-soft）——审计附件非状态。
+ * @param {{ specBase: string, stage: string, changeName: string, envelope: object }} opts
+ * @returns {string|null} 成功返回落盘路径；失败返回 null
+ */
+export function writeGateResultArtifact({ specBase, stage, changeName, envelope }) {
+  try {
+    const runsDir = join(specBase, '.runtime', 'verify-runs')
+    const resultPath = join(runsDir, `gate-${stage}-${changeName}.json`)
+    mkdirSync(runsDir, { recursive: true })
+    writeFileSync(resultPath, JSON.stringify({
+      written_at: new Date().toISOString(),
+      stage,
+      change: changeName,
+      envelope,
+    }, null, 2) + '\n')
+    return resultPath
+  } catch {
+    return null // fail-soft：落盘是审计附件，失败只缺附件不误门
+  }
+}

package/src/module-impact.js

@@ -48,7 +48,15 @@ export function parseModuleMapPaths(yamlText) {
     }
     if (inPaths && currentModule) {
       const item = line.match(/^      - (.+)$/)
-      if (item) map.get(currentModule).push(item[1].trim().replace(/\\/g, '/'))
+      if (item) {
+        // 引号剥离（坑 map-quoted-path-deadmatch，2026-09-21 R4-L 实证）：docs/<p>/modules/
+        // _module-map.yaml 存在带引号条目（"frontend/src/app/page.tsx"）——只 trim 不剥引号时
+        // classifyFile 的 === / startsWith 恒失配，引号条目全是死路径（frontend map 790 条
+        // 几乎全带引号＝整图失效）。仅首尾成对引号才剥（路径内部引号不动）。
+        const raw = item[1].trim()
+        const unquoted = raw.replace(/^(['"])([\s\S]*)\1$/, '$2')
+        map.get(currentModule).push(unquoted.replace(/\\/g, '/'))
+      }
     }
   }
   return map
@@ -89,18 +97,33 @@ export function syncModuleDocSidecars({ cwd, changeName, note, specDir = null })
   // 复用 generateModuleImpactSkeleton 的 map 发现 + 归类（diff 来源）
   const skel = generateModuleImpactSkeleton({ cwd, changeName, specDir })
   if (!skel) return { synced: [], unmatched: [], skipped: [], reason: '无 module-map 或无 diff 可归类' }
-  const modulesDir = findModulesDir(specBase)
-  if (!modulesDir) return { synced: [], unmatched: [], skipped: [], reason: 'modules 目录不存在' }
-  // 从骨架 markdown 反解归类结果（命中模块集合 + 未匹配清单）
-  const hitModules = [...skel.markdown.matchAll(/^\| (\S+) \| `([^`]+)`/gm)].map(m => m[1])
-  const unmatched = [...skel.markdown.matchAll(/^- `([^`]+)` /gm)].map(m => m[1])
+  // 结构化归类直用（classified 含 project 归属；multimap-first-found-mismatch 同坑修复面）——
+  // 不再反解 markdown（正则脆且丢 project 维度）。classified 缺席时兜底反解 + 首个 modules 目录。
+  let mods = []
+  if (Array.isArray(skel.classified) && skel.classified.length >= 0) {
+    const seen = new Set()
+    for (const r of skel.classified) {
+      const key = r.project + '/' + r.module
+      if (seen.has(key)) continue
+      seen.add(key)
+      mods.push({ project: r.project, module: r.module, modulesDir: join(specBase, 'docs', r.project, 'modules') })
+    }
+  } else {
+    const modulesDir = findModulesDir(specBase)
+    if (!modulesDir) return { synced: [], unmatched: [], skipped: [], reason: 'modules 目录不存在' }
+    mods = [...new Set([...skel.markdown.matchAll(/^\| (\S+) \| `([^`]+)`/gm)].map(m => m[1]))]
+      .map(mod => ({ project: null, module: mod, modulesDir }))
+  }
+  const unmatched = Array.isArray(skel.unmatchedFiles)
+    ? skel.unmatchedFiles
+    : [...skel.markdown.matchAll(/^- `([^`]+)` /gm)].map(m => m[1])
   const synced = []
   const skipped = []
-  for (const mod of [...new Set(hitModules)]) {
+  for (const { project: proj, module: mod, modulesDir } of mods) {
     const sidecarPath = join(modulesDir, `${mod}.changelog.md`)
     let sidecar = ''
     try { sidecar = readFileSync(sidecarPath, 'utf8') } catch { sidecar = '' }
-    if (sidecar.includes(`- ${changeName} |`)) { skipped.push(mod); continue }
+    if (sidecar.includes(`- ${changeName} |`)) { skipped.push(proj ? `${proj}/${mod}` : mod); continue }
     const NL = String.fromCharCode(10)
     const line = `- ${changeName} | ${note || '(见该变更 quicklog/归档)'}`
     const base = sidecar
@@ -114,7 +137,7 @@ export function syncModuleDocSidecars({ cwd, changeName, note, specDir = null })
       const stamped = card.replace(/^updated_at:.*$/m, `updated_at: ${new Date().toISOString().slice(0, 19) + '+08:00'}`)
       if (stamped !== card) writeFileSync(cardPath, stamped)
     } catch { /* 卡不存在——sidecar 照写，卡内容留给 agent */ }
-    synced.push(mod)
+    synced.push(proj ? `${proj}/${mod}` : mod)
   }
   return { synced, unmatched, skipped }
 }
@@ -133,22 +156,22 @@ function findModulesDir(specBase) {
 export function generateModuleImpactSkeleton({ cwd, changeName, specDir = null, sourceFiles = null, origin = null }) {
   const specBase = resolveSpecDir(cwd, { specDir })
 
-  // 找 _module-map.yaml（docs/<p>/modules/；多项目取首个含 modules 索引的）
-  let moduleMapPath = null
+  // 多项目 map 联合归类（坑 multimap-first-found-mismatch，2026-09-21 R4-L 实证）：docs/ 下
+  // 各项目可各带 _module-map.yaml（对撞仓 5 个），原「取首个命中」让 daemon/frontend 文件对
+  // 按目录序排前的 backend map 全失配——24 文件全未匹配、sidecar 也写错项目目录。联合口径：
+  // 逐项目 classify、目录序首个命中 wins（单项目时联合退化为一图，行为不变）。
+  const moduleMaps = []
   try {
     for (const p of readdirSync(join(specBase, 'docs'), { withFileTypes: true })) {
       if (!p.isDirectory()) continue
       const candidate = join(specBase, 'docs', p.name, 'modules', '_module-map.yaml')
       if (existsSync(candidate)) {
-        moduleMapPath = candidate
-        break
+        const pm = parseModuleMapPaths(readFileSync(candidate, 'utf8'))
+        if (pm.size > 0) moduleMaps.push({ project: p.name, modulePaths: pm })
       }
     }
   } catch { /* 无 docs/ */ }
-  if (!moduleMapPath) return null
-
-  const modulePaths = parseModuleMapPaths(readFileSync(moduleMapPath, 'utf8'))
-  if (modulePaths.size === 0) return null
+  if (moduleMaps.length === 0) return null
 
   let sourceFileList
   if (sourceFiles) {
@@ -169,12 +192,18 @@ export function generateModuleImpactSkeleton({ cwd, changeName, specDir = null,
   if (sourceFileList.length === 0) return null
 
   const byModule = new Map()
+  const classified = [] // {project, module, file}——syncModuleDocSidecars 按 project 落 sidecar 用
   const unmatched = []
   for (const f of sourceFileList) {
-    const mod = classifyFile(f, modulePaths)
-    if (mod) {
-      if (!byModule.has(mod)) byModule.set(mod, [])
-      byModule.get(mod).push(f)
+    let hit = null
+    for (const m of moduleMaps) {
+      const mod = classifyFile(f, m.modulePaths)
+      if (mod) { hit = { project: m.project, moduleId: mod }; break }
+    }
+    if (hit) {
+      if (!byModule.has(hit.moduleId)) byModule.set(hit.moduleId, [])
+      byModule.get(hit.moduleId).push(f)
+      classified.push({ project: hit.project, module: hit.moduleId, file: f })
     } else {
       unmatched.push(f)
     }
@@ -234,5 +263,5 @@ export function generateModuleImpactSkeleton({ cwd, changeName, specDir = null,
   L.push('规则：execute/verify 完成文档同步后把对应行回填 done；确定不同步的行改 skipped 并在操作列写明原因。')
   L.push('')
 
-  return { markdown: L.join('\n'), matchedCount: sourceFileList.length - unmatched.length, unmatchedCount: unmatched.length }
+  return { markdown: L.join('\n'), matchedCount: sourceFileList.length - unmatched.length, unmatchedCount: unmatched.length, classified, unmatchedFiles: unmatched }
 }

package/src/run/bg-sync.js

@@ -0,0 +1,231 @@
+/**
+ * spec-sync 后台异步执行（detached 子进程）。
+ *
+ * 背景（2026-09-20 用户反馈：末步 --done 因 spec-sync 网络同步约 4 分钟不返回）：
+ * triggerSync 的 17 个调用点全部 fire-and-forget，但 Node 进程退出要等事件循环排空——
+ * 在飞 fetch 拖住进程，CLI 输出打完后仍要等网络收尾才返回 shell（平台慢时分钟级体感
+ * hang；本机制落地当天的会话启动命令尾部 3 行 [spec-sync] 已同步 逐条等网络，现场即
+ * 实证）。8s 总熔断（raceWithAbort）只保证「最多等 8s」，治标；本模块治本：同步整体
+ * 挪进 detached 后台子进程，父进程 spawn + unref 后立即返回，命令零网络尾巴。
+ *
+ * 架构（父侧/子侧同一模块，职责分开）：
+ * - 父侧 spawnBackgroundSync（shared.js triggerSync 唯一接入点调用）：
+ *   ① 未连接平台预判（sync.js peekPlatformConnected 同源判据）——未连接不 spawn，
+ *     本地独立用户零开销零行为变化；② 单飞锁判定：活锁 → rerunQueued 置位合并
+ *     （跑完当前轮再补一轮，防进程堆积），无锁/死锁 → spawn detached 子进程。
+ * - 子侧 runBgSyncFromEnv（node -e bootstrap 动态 import 本模块）：写锁 → 循环
+ *   〔清 rerunQueued → triggerSync inline 执行一轮 → 期间有新请求则再来一轮〕，
+ *   上限 5 轮 / 总预算 ~2.5min → 清锁退出。轮前清位 + 轮后查位：清位后本轮树 hash
+ *   晚于清位时刻，天然覆盖此后到达的状态；hash 之后到达的靠置位标记触发下一轮。
+ * - 子进程 stdout/stderr 接 <runtimeRoot>/spec-sync-bg.log（append，超 1MB 截尾保
+ *   后 512KB）：[spec-sync]/[sync] 的 warn/冲突横幅全量留痕，不进主命令输出也不再丢。
+ *
+ * 与既有机制的交互：
+ * - raceWithAbort / SILLYSPEC_SYNC_TIMEOUT_MS 不动——inline 路径原样。后台轮预算 =
+ *   max(resolveSyncTotalTimeoutMs(), 45s)：后台无人等待，放宽到 45s 提高「慢平台真的
+ *   同步成功」概率（2026-09-07 平台 >8s 响应间歇熔断的 pain 点在后台模式下自然消解）。
+ * - sync-noise.js 噪音闸 / spec-sync-conflict-*.json / 基线快照在子进程内照常工作
+ *   （同一 .runtime 目录，跨进程 marker 语义不变）。
+ * - 冲突可见性不降级：横幅进日志文件 + 冲突文件照落，下一条命令 progress show 照常
+ *   红标提示（resolve 三态处置入口不变）。
+ * - SILLYSPEC_SYNC_BG=0 逃生阀：triggerSync 回落 inline（测试断言进程内行为/用户自救）。
+ *
+ * 循环 import 说明：本模块与 shared.js 双向引用（shared 调本模块 spawnBackgroundSync、
+ * 本模块两侧调 shared 的 triggerSync/resolveRuntimeRoot/resolveSyncTotalTimeoutMs）。
+ * 对 shared 的引用一律走函数内动态 import，避免静态环（ESM 环可运行但初始化序脆弱，
+ * 刻意不赌）；父进程内 shared.js 已加载，动态 import 走缓存无额外成本。
+ */
+import { spawn } from 'child_process';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+export const BG_LOCK_FILENAME = 'spec-sync-bg.lock';
+export const BG_LOG_FILENAME = 'spec-sync-bg.log';
+
+// 后台轮参数：单轮预算下限（与 env SILLYSPEC_SYNC_TIMEOUT_MS 取 max）、轮数与总预算帽
+// （防慢平台下无限续轮）；锁时效（pid 活性之外的第二道判死——pid 复用假活兜底，
+// 子进程自身总预算 ~2.5min + 收尾余量远小于该值，超时必是异常残留）。
+const BG_ROUND_FLOOR_MS = 45_000;
+const BG_MAX_ROUNDS = 5;
+const BG_TOTAL_BUDGET_MS = 150_000;
+const LOCK_STALE_MS = 15 * 60 * 1000;
+const LOG_TRUNCATE_THRESHOLD = 1_000_000;
+const LOG_TRUNCATE_KEEP = 512 * 1024;
+
+/** pid 活性探测（跨平台）：signal 0 探测；EPERM = 进程存在但属他户，保守按活。 */
+function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e && e.code === 'EPERM';
+  }
+}
+
+/** 读后台单飞锁（缺失/损坏 → null）。 */
+export function readBgSyncLock(runtimeRoot) {
+  try {
+    const raw = readFileSync(join(runtimeRoot, BG_LOCK_FILENAME), 'utf8');
+    const obj = JSON.parse(raw);
+    return obj && typeof obj === 'object' ? obj : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeBgSyncLock(runtimeRoot, lock) {
+  mkdirSync(runtimeRoot, { recursive: true });
+  const tmp = join(runtimeRoot, `${BG_LOCK_FILENAME}.${process.pid}.tmp`);
+  writeFileSync(tmp, JSON.stringify(lock) + '\n', 'utf8');
+  renameSync(tmp, join(runtimeRoot, BG_LOCK_FILENAME));
+}
+
+function removeBgSyncLock(runtimeRoot) {
+  try {
+    const p = join(runtimeRoot, BG_LOCK_FILENAME);
+    if (existsSync(p)) unlinkSync(p);
+  } catch { /* 清锁失败：残留锁按时效/pid 判死后自动接管，不影响正确性 */ }
+}
+
+/**
+ * 锁活性判定（pid 活 + 未超时）。纯函数（pid 探测单列 isPidAlive 便于注入测试）。
+ * @param {object|null} lock readBgSyncLock 产物
+ * @param {number} [now] 注入时钟（测试用）
+ */
+export function isBgSyncLockLive(lock, now = Date.now()) {
+  if (!lock || !Number.isInteger(lock.pid) || lock.pid <= 0) return false;
+  if (typeof lock.startedAt !== 'number') return false;
+  if (now - lock.startedAt > LOCK_STALE_MS) return false;
+  return isPidAlive(lock.pid);
+}
+
+/** 子进程起步截尾日志（>1MB 保后 512KB，从整行边界起）。失败只影响日志体积。 */
+function truncateLogIfNeeded(runtimeRoot) {
+  try {
+    const p = join(runtimeRoot, BG_LOG_FILENAME);
+    if (statSync(p).size <= LOG_TRUNCATE_THRESHOLD) return;
+    const buf = readFileSync(p);
+    const keep = buf.subarray(Math.max(0, buf.length - LOG_TRUNCATE_KEEP));
+    const nl = keep.indexOf(10);
+    writeFileSync(p, nl >= 0 ? keep.subarray(nl + 1) : keep);
+  } catch { /* 截断失败：继续 append */ }
+}
+
+/** 子进程 bootstrap：node -e 动态 import 本模块（file URL 精确定位，不依赖 CLI 安装形态）。 */
+function buildChildBootstrap() {
+  const selfUrl = new URL('./bg-sync.js', import.meta.url).href;
+  return `import(${JSON.stringify(selfUrl)}).then(m=>m.runBgSyncFromEnv()).catch(e=>{console.error('[spec-sync-bg] 后台同步进程异常退出:',(e&&e.message)||e)});`;
+}
+
+/**
+ * 父侧后台同步入口（triggerSync 调用，不直接被业务代码使用）。
+ *
+ * @returns {Promise<{status:'spawned'|'coalesced'|'not-connected', logPath?:string}>}
+ *   spawned=已起后台子进程；coalesced=活锁在跑、本轮状态已并入其下一轮（rerunQueued）；
+ *   not-connected=未连接平台（调用方回落 inline 路径=与旧行为一致的静默 no-op）。
+ *   spawn 失败抛异常（调用方 catch 降级 inline，绝不因后台化阻断主流程）。
+ */
+export async function spawnBackgroundSync(cwd, changeName, platformOpts = {}, opts = {}) {
+  const syncMod = await import('../sync.js');
+  if (!syncMod.peekPlatformConnected(cwd)) return { status: 'not-connected' };
+
+  const { resolveRuntimeRoot } = await import('./shared.js');
+  const runtimeRoot = resolveRuntimeRoot(platformOpts, platformOpts?.specRoot || join(cwd, '.sillyspec'));
+
+  const lock = readBgSyncLock(runtimeRoot);
+  if (isBgSyncLockLive(lock)) {
+    // 单飞合并：活后台轮在跑，把「还有新状态要同步」并入其下一轮。置位失败（并发写锁）
+    // 只损失合并信号——后台轮收尾锁自清，下一条命令重新 spawn，收敛不丢。
+    try { writeBgSyncLock(runtimeRoot, { ...lock, rerunQueued: true }); } catch { /* 见上 */ }
+    return { status: 'coalesced', logPath: join(runtimeRoot, BG_LOG_FILENAME) };
+  }
+
+  // 日志 fd：子进程 stdout/stderr 直接 append 进日志文件（跨平台 fd 继承）；开不了退 ignore
+  const logPath = join(runtimeRoot, BG_LOG_FILENAME);
+  let stdio = ['ignore', 'ignore', 'ignore'];
+  let logFd = null;
+  try {
+    mkdirSync(runtimeRoot, { recursive: true });
+    logFd = openSync(logPath, 'a');
+    stdio = ['ignore', logFd, logFd];
+  } catch {
+    logFd = null;
+  }
+
+  const env = {
+    ...process.env,
+    SILLYSPEC_BG_SYNC_CHANGE: String(changeName),
+    SILLYSPEC_BG_SYNC_CWD: String(cwd),
+  };
+  if (platformOpts?.specRoot) env.SILLYSPEC_BG_SYNC_SPEC_ROOT = String(platformOpts.specRoot);
+  if (platformOpts?.runtimeRoot) env.SILLYSPEC_BG_SYNC_RUNTIME_ROOT = String(platformOpts.runtimeRoot);
+
+  try {
+    const child = (opts.spawnImpl || spawn)(process.execPath, ['-e', buildChildBootstrap()], {
+      cwd,
+      detached: true,
+      stdio,
+      windowsHide: true,
+      env,
+    });
+    child.unref?.();
+  } finally {
+    if (logFd !== null) {
+      try { closeSync(logFd); } catch { /* 父侧 fd 副本关闭；子进程持有继承副本 */ }
+    }
+  }
+  return { status: 'spawned', logPath };
+}
+
+/**
+ * 子侧入口（bootstrap 经 env 传参调起；env 注入默认值供测试覆盖）。
+ *
+ * 单飞循环：写锁（本 pid）→ 每轮清 rerunQueued 后 inline 跑一轮 triggerSync →
+ * 轮末查位，被置位且预算未尽则续轮（迟到状态收敛），否则清锁退出。
+ * 锁 pid 非本进程（双 spawn 竞态窗口被后写者接管）→ 让位退出防双跑。
+ */
+export async function runBgSyncFromEnv(env = process.env) {
+  const changeName = env.SILLYSPEC_BG_SYNC_CHANGE;
+  const cwd = env.SILLYSPEC_BG_SYNC_CWD;
+  if (!changeName || !cwd) return;
+
+  const platformOpts = {};
+  if (env.SILLYSPEC_BG_SYNC_SPEC_ROOT) platformOpts.specRoot = env.SILLYSPEC_BG_SYNC_SPEC_ROOT;
+  if (env.SILLYSPEC_BG_SYNC_RUNTIME_ROOT) platformOpts.runtimeRoot = env.SILLYSPEC_BG_SYNC_RUNTIME_ROOT;
+
+  const { triggerSync, resolveRuntimeRoot, resolveSyncTotalTimeoutMs } = await import('./shared.js');
+  const runtimeRoot = resolveRuntimeRoot(platformOpts, platformOpts.specRoot || join(cwd, '.sillyspec'));
+  truncateLogIfNeeded(runtimeRoot);
+  const startedAt = Date.now();
+  writeBgSyncLock(runtimeRoot, { pid: process.pid, startedAt, change: changeName, rerunQueued: false });
+
+  const roundTimeoutMs = Math.max(resolveSyncTotalTimeoutMs(), BG_ROUND_FLOOR_MS);
+  const deadline = startedAt + BG_TOTAL_BUDGET_MS;
+  for (let round = 1; round <= BG_MAX_ROUNDS; round++) {
+    // 轮前清位：本轮 triggerSync 的树 hash 晚于清位时刻，覆盖此后到达的全部状态；
+    // 读→写间隙内的置位存在丢失窗口（毫秒级），由下一条命令的同步兜底收敛。
+    const cur = readBgSyncLock(runtimeRoot);
+    writeBgSyncLock(runtimeRoot, { pid: process.pid, startedAt: cur?.startedAt || startedAt, change: changeName, rerunQueued: false });
+    console.log(`[spec-sync-bg] 第 ${round}/${BG_MAX_ROUNDS} 轮开始 ${new Date().toISOString()}: ${changeName}`);
+    try {
+      await triggerSync(cwd, changeName, platformOpts, { inline: true, timeoutMs: roundTimeoutMs });
+    } catch (e) {
+      console.warn(`[spec-sync-bg] 本轮同步异常（best-effort，下一条命令自动重试）: ${(e && e.message) || e}`);
+    }
+    const lock = readBgSyncLock(runtimeRoot);
+    if (!lock || lock.pid !== process.pid) {
+      console.warn('[spec-sync-bg] 锁已不属于本进程（被并行 spawn 接管），让位退出');
+      return;
+    }
+    if (!lock.rerunQueued) break;
+    if (Date.now() + roundTimeoutMs > deadline) {
+      console.warn('[spec-sync-bg] 总预算用尽，残留待同步状态由下一条命令的同步接管');
+      break;
+    }
+  }
+  console.log(`[spec-sync-bg] 后台同步完成 ${new Date().toISOString()}: ${changeName}`);
+  removeBgSyncLock(runtimeRoot);
+}
+
+export default { spawnBackgroundSync, runBgSyncFromEnv, readBgSyncLock, isBgSyncLockLive, isPidAlive };

package/src/run/command.js

@@ -511,6 +511,10 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
         console.error(`❌ 检测到祖先链有 ${ancestorSpecs.length} 个 .sillyspec 实例(monorepo 多实例)，当前使用: ${specBase}`)
         console.error(`   当前 cwd 不在 git 顶层仓库根下，静默绑定到子项目实例会导致进度/QUICKLOG 分裂。`)
         console.error(`   修复：cd 回项目根目录，或用 --spec-dir <根>/.sillyspec 显式指定。`)
+        // 一键指定整行（R4-S-Q 实证：嵌套 worktree 场景下 agent 多次试错才拼对放行组合）——
+        // 意图实例即当前最近命中（specBase），直接给出可贴完整命令行。
+        console.error(`   一键指定（当前最近实例，整行照贴）：`)
+        console.error(`   sillyspec ${process.argv.slice(2).join(' ')} --spec-dir "${specBase}"`)
         process.exit(2)
       }
       // 在 git 根下但有多实例(子项目也有 .sillyspec)→ 仅警告(正确实例已命中)