sillyspec 3.20.6 → 3.20.7

package/src/run.js

@@ -1341,7 +1341,18 @@ export async function runCommand(args, cwd, specDir = null) {
     inputText = flags[inputIdx + 1]
   }
 
-  // 解析 --change <name>（quick 阶段支持逗号分隔多值，作为「关联变更」）
+  // 解析 --linked-changes <a,b|none>（quick 专用：显式声明关联变更，CI/脚本友好）
+  // 与 --change 解耦：--linked-changes 语义清晰（关联变更），不与「指定变更名」混淆。
+  // null = 未指定（走持久化/交互/兼容回退）；[] = 显式 none（不关联）；[...] = 显式列表
+  let explicitLinked = null
+  const linkedIdx = flags.indexOf('--linked-changes')
+  if (linkedIdx !== -1 && flags[linkedIdx + 1]) {
+    const v = flags[linkedIdx + 1].trim()
+    explicitLinked = v.toLowerCase() === 'none' ? [] : v.split(',').map(s => s.trim()).filter(Boolean)
+  }
+
+  // 解析 --change <name>（quick 阶段向后兼容：逗号分隔作为「关联变更」；
+  // 历史写法，语义与「指定变更名」冲突，新用法建议改用 --linked-changes）
   let changeName = null
   let linkedChanges = []
   const changeIdx = flags.indexOf('--change')
@@ -1352,6 +1363,10 @@ export async function runCommand(args, cwd, specDir = null) {
       changeName = null
     }
   }
+  // --linked-changes 优先于 --change（显式 > 隐式兼容）
+  if (explicitLinked !== null) {
+    linkedChanges = explicitLinked
+  }
   // quick 的 progress 键固定走 'default'：归属语义已由 linkedChanges 承担（→ quick-guard.json
   // → <linked-changes> 占位符注入 prompt）。progress 不能走 pm.read(cwd, null) 的自动检测——
   // 多活跃 change 项目里 quick 步骤进度会随活跃 change 增减在各 change/default 间漂移，
@@ -1376,7 +1391,7 @@ export async function runCommand(args, cwd, specDir = null) {
     '--done', '--skip', '--status', '--reset', '--confirm', '--skip-approval',
     '--wait', '--continue', '--non-interactive', '--interactive',
     '--reason', '--options', '--answer', '--confirm-mode',
-    '--output', '--input', '--change',
+    '--output', '--input', '--change', '--linked-changes',
     '--spec-dir', '--spec-root', '--runtime-root', '--workspace-id', '--scan-run-id',
     '--files', '--allow-new', '--force-baseline', '--force-rescan',
     '--json', '--dir', '--help',
@@ -1400,13 +1415,28 @@ export async function runCommand(args, cwd, specDir = null) {
 
   const pm = new ProgressManager({ specDir: specRoot })
 
-  // quick 阶段：多变更交互式选择关联变更（--change 未指定时）
-  if (stageName === 'quick' && linkedChanges.length === 0) {
-    linkedChanges = await resolveQuickLinkedChanges({
-      pm, cwd, specDir: specRoot, quickFiles,
-      taskDescription: inputText || '',
-      nonInteractive: isNonInteractive,
-    })
+  // quick 阶段：确定关联变更
+  // 优先级：--linked-changes / --change 显式 > 已持久化 quick-guard.json（--done 复用）> 交互式 > 非交互 fallback
+  // 关键：--done 收尾时复用首次 run 持久化的 linkedChanges，不在管道/CI 下重复弹交互 prompt。
+  // explicitLinked === null 且未传 --change 时才进入此分支（显式 --linked-changes none 不应触发交互）。
+  if (stageName === 'quick' && explicitLinked === null && linkedChanges.length === 0) {
+    const guardFile = join(specRoot, '.runtime', 'quick-guard.json')
+    let persistedLinked = null
+    try {
+      if (existsSync(guardFile)) {
+        const g = JSON.parse(readFileSync(guardFile, 'utf8'))
+        if (Array.isArray(g.linkedChanges)) persistedLinked = g.linkedChanges
+      }
+    } catch {}
+    if (persistedLinked) {
+      linkedChanges = persistedLinked
+    } else {
+      linkedChanges = await resolveQuickLinkedChanges({
+        pm, cwd, specDir: specRoot, quickFiles,
+        taskDescription: inputText || '',
+        nonInteractive: isNonInteractive,
+      })
+    }
   }
 
   let progress = await pm.read(cwd, changeName)
@@ -1607,7 +1637,7 @@ async function resolveQuickLinkedChanges({ pm, cwd, specDir, quickFiles, taskDes
   if (activeChanges.length === 0) return []
   if (activeChanges.length === 1) return [activeChanges[0]]
 
-  if (nonInteractive || process.stdin.isTTY === false) {
+  if (nonInteractive || !process.stdin.isTTY) {
     console.log('💡 非交互环境，已默认不关联变更；如需关联请用 --change a,b')
     return []
   }
@@ -1702,7 +1732,10 @@ async function runStage(pm, progress, stageName, cwd, changeName, skipApproval =
         console.log(`🔗 worktree 已创建: ${result.worktreePath} (分支: ${result.branch}, 模式: ${result.mode})`)
       } catch (e) {
         console.error(`❌ worktree 创建失败: ${e.message}`)
-        console.error(`   继续执行前请解决上述问题，或使用 --no-worktree 跳过。`)
+        console.error(`   修复建议：`)
+        console.error(`   1. 运行 sillyspec worktree doctor --fix 检查并修复 worktree 状态`)
+        console.error(`   2. 或手动清理残留：git worktree prune && git branch -D sillyspec/${effectiveChange}`)
+        console.error(`   3. 必要时删除残留目录 .sillyspec/.runtime/worktrees/${effectiveChange}/ 后重试`)
         process.exit(1)
       }
     }
@@ -2024,6 +2057,13 @@ async function archiveChangeDirectory(pm, cwd, progress, specBase) {
     console.error(`❌ 归档失败：源目录不存在 ${srcDir}`)
     process.exit(1)
   }
+  // 移动前硬校验：变更包必须含 plan.md，否则不该归档。
+  // 在移动前阻断（而非移动后），目录尚未动，用户可直接修复后重试。
+  if (!existsSync(join(srcDir, 'plan.md'))) {
+    console.error(`❌ 归档失败：变更目录缺少 plan.md（${srcDir}）`)
+    console.error(`   plan.md 是归档的必需产物。请先补全 plan 阶段产出再归档。`)
+    process.exit(1)
+  }
   if (existsSync(destDir)) {
     console.error(`❌ 归档失败：目标目录已存在 ${destDir}`)
     process.exit(1)
@@ -2037,7 +2077,32 @@ async function archiveChangeDirectory(pm, cwd, progress, specBase) {
   }
 
   await pm.unregisterChange(cwd, archiveChangeName)
+
+  // 归档时清理可能残留的 worktree（execute 自动清理未走到 / 有未 apply 变更被遗弃）。
+  // 安全策略：有未 apply 变更时保留 worktree 并警告，避免误删用户未应用的代码。
+  try {
+    const { WorktreeManager } = await import('./worktree.js')
+    const wm = new WorktreeManager({ cwd })
+    const meta = wm.getMeta(archiveChangeName)
+    if (meta) {
+      const check = meta.mode !== 'in-place-fallback' ? wm.hasUnappliedChanges(archiveChangeName) : { hasChanges: false }
+      if (check.hasChanges) {
+        console.warn(`⚠️  归档时 worktree 仍有 ${check.changedFiles.length} 个未 apply 变更，保留 worktree`)
+        console.warn(`   确认不需要后手动清理: sillyspec worktree cleanup ${archiveChangeName} --force`)
+      } else {
+        const cleanResult = wm.cleanup(archiveChangeName)
+        if (cleanResult.residual?.length > 0) {
+          console.warn(`⚠️  归档 worktree 清理残留: ${cleanResult.residual.join('; ')}`)
+          console.warn(`   手动处理: sillyspec worktree cleanup ${archiveChangeName} --force`)
+        }
+      }
+    }
+  } catch (e) {
+    console.warn(`⚠️  归档 worktree 清理失败（不阻断归档）: ${e.message}`)
+  }
+
   console.log(`📦 已归档：${archiveChangeName} → archive/${date}-${archiveChangeName}/`)
+  return destDir
 }
 
 // ── Wait Step ──
@@ -2249,9 +2314,8 @@ async function continueStep(pm, progress, stageName, cwd, answer, options = {})
           console.log('🔗 Worktree: n/a (no meta)');
         } else if (meta.mode === 'native-worktree') {
           console.log('🔗 Worktree: kept (外部隔离环境)');
-        } else if (meta.mode === 'in-place-fallback') {
-          console.log('🔗 Worktree: n/a (in-place 模式)');
         } else {
+          // in-place 模式不再短路：cleanup 现在能安全处理 in-place（只清 meta，不碰主工作区）
           const check = wm.hasUnappliedChanges(changeName);
           if (check.hasChanges) {
             console.log(`🔗 Worktree: pending apply (${check.changedFiles.length} 个未应用变更)`);
@@ -2259,6 +2323,10 @@ async function continueStep(pm, progress, stageName, cwd, answer, options = {})
           } else {
             const cleanResult = wm.cleanup(changeName);
             console.log(`🔗 Worktree: ${cleanResult.result}`);
+            if (cleanResult.residual?.length > 0) {
+              console.warn(`   ⚠️ 清理残留: ${cleanResult.residual.join('; ')}`);
+              console.warn(`   手动处理: sillyspec worktree cleanup ${changeName} --force`);
+            }
           }
         }
       } catch (e) {
@@ -2375,6 +2443,7 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
   const specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
   const stageData = progress.stages[stageName]
   const scanProfile = stageData?.scanProfile || null
+  let archivedDir = null // archive step「确认归档」实际归档目录（archiveChangeDirectory 返回）
 
   // ── WAIT MARKER 硬校验 ──
   // 如果 output 包含等待标记，拒绝 --done 推进
@@ -2462,23 +2531,22 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
       console.log('⚠️  请添加 --confirm 确认归档，例如：sillyspec run archive --done --confirm --output "确认归档"')
       return { stageCompleted: false, currentIdx, nextPendingIdx: currentIdx }
     }
-    await archiveChangeDirectory(pm, cwd, progress, specBase)
+    archivedDir = await archiveChangeDirectory(pm, cwd, progress, specBase)
   }
 
   // archive "确认归档" 步骤完成后，校验归档完整性
   if (stageName === 'archive' && steps[currentIdx]?.name === '确认归档' && confirm) {
-    const projectName = progress.project || basename(cwd)
-    const contractResult = runValidators('archive', cwd, changeName, { projectName, specRoot: platformOpts?.specRoot })
-    if (contractResult.errors.length > 0) {
-      console.error(`\n❌ 归档校验失败：`)
-      for (const err of contractResult.errors) {
-        console.error(`   - ${err}`)
-      }
-    }
-    if (contractResult.warnings.length > 0) {
-      console.warn(`\n⚠️ 归档校验警告：`)
-      for (const w of contractResult.warnings) {
-        console.warn(`   - ${w}`)
+    // contracts.archive.validators 为空数组（两个 validator 生效窗口互斥，注册为阶段级会误报），
+    // 故 runValidators('archive') 是空跑。这里直接对实际归档目录做内容完整性校验。
+    // plan.md 已在 archiveChangeDirectory 移动前硬校验阻断，此处只查推荐文档。
+    if (archivedDir && existsSync(archivedDir)) {
+      const recommendedDocs = ['design.md', 'module-impact.md']
+      const missingRecommended = recommendedDocs.filter(d => !existsSync(join(archivedDir, d)))
+      if (missingRecommended.length > 0) {
+        console.warn(`\n⚠️ 归档校验警告：归档目录缺少推荐文档`)
+        for (const d of missingRecommended) console.warn(`   - ${d}（${archivedDir}）`)
+      } else {
+        console.log(`\n✅ 归档校验通过：核心文档齐全`)
       }
     }
   }
@@ -2936,10 +3004,11 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
         // summary 失败不影响主流程
         console.log('\n👉 下一步：sillyspec run verify（验证通过后才能归档）')
       }
-    } else if (stageName === 'verify') {
-      console.log('\n👉 下一步：sillyspec run archive（验证通过，可以归档了）')
     } else if (stageName === 'archive') {
       console.log('\n👉 归档完成！现在可以提交了：git commit -m "..."')
+    } else if (stageName === 'verify') {
+      // verify 的"验证通过"提示延后到下方 validator 通过后才打印，
+      // 避免校验失败（FAIL / 缺 verify-result.md）时仍声称"验证通过可以归档"。
     } else {
       console.log(`\n下一步由你决定：sillyspec run <stage>（brainstorm/plan/execute/verify/archive 等）`)
     }
@@ -2954,6 +3023,13 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
           console.error(`   - ${err}`)
         }
         console.error(`\n   提示：修复缺失产物后重新运行此步骤，或使用 --skip-approval 跳过校验`)
+        // 产物校验失败必须阻断完成 —— 否则 validator 形同虚设，
+        // verify 会带着 FAIL/缺 verify-result.md 被 ✅ 标记完成（历史教训）。
+        // plan/execute 的专项契约校验（下方）在产物齐全后才需要继续跑，故此处先 return。
+        progress.lastActive = new Date().toLocaleString('zh-CN',{hour12:false})
+        await pm._write(cwd, progress, changeName)
+        triggerSync(cwd, changeName, platformOpts)
+        return { stageCompleted: false, currentIdx, nextPendingIdx: currentIdx }
       }
       if (contractResult.warnings.length > 0) {
         console.warn(`\n⚠️ 阶段 ${stageName} 校验警告：`)
@@ -2962,6 +3038,11 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
         }
       }
 
+      // verify 产物校验通过 + 结论非 FAIL（否则上面已阻断），此时才能声称"验证通过"
+      if (stageName === 'verify') {
+        console.log('\n✅ 验证通过，下一步：sillyspec run archive')
+      }
+
       // ── Plan postcheck contract：plan.md 必须满足 execute 契约 ──
       if (stageName === 'plan') {
         const planFile = resolveChangeDir(cwd, progress, platformOpts?.specRoot)
@@ -3061,23 +3142,21 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
           console.log('🔗 Worktree: n/a (no meta)');
         } else if (meta.mode === 'native-worktree') {
           console.log('🔗 Worktree: kept (外部隔离环境)');
-        } else if (meta.mode === 'in-place-fallback') {
-          console.log('🔗 Worktree: n/a (in-place 模式)');
         } else {
+          // in-place 模式不再短路：cleanup 现在能安全处理 in-place（只清 meta，不碰主工作区）
           const check = wm.hasUnappliedChanges(changeName);
           if (check.hasChanges) {
             console.log(`🔗 Worktree: pending apply (${check.changedFiles.length} 个未应用变更)`);
             console.log(`   下一步: sillyspec worktree apply ${changeName}`);
           } else {
             const cleanResult = wm.cleanup(changeName);
-            if (cleanResult.result === 'skipped' || cleanResult.result === 'kept') {
-              console.log(`🔗 Worktree: ${cleanResult.result}`);
-            } else {
-              console.log(`🔗 Worktree: ${cleanResult.result}`);
-              if (cleanResult.details?.length > 0) {
-                for (const d of cleanResult.details) {
-                  if (d.startsWith('⚠️')) console.log(`   ${d}`);
-                }
+            console.log(`🔗 Worktree: ${cleanResult.result}`);
+            if (cleanResult.residual?.length > 0) {
+              console.warn(`   ⚠️ 清理残留: ${cleanResult.residual.join('; ')}`);
+              console.warn(`   手动处理: sillyspec worktree cleanup ${changeName} --force`);
+            } else if (cleanResult.details?.length > 0) {
+              for (const d of cleanResult.details) {
+                if (d.startsWith('⚠️')) console.log(`   ${d}`);
               }
             }
           }
@@ -3333,6 +3412,28 @@ function showStatus(progress, stageName) {
 }
 
 async function resetStage(pm, progress, stageName, cwd, changeName, platformOpts = {}) {
+  // execute 阶段 reset 时清理自建 worktree，否则下次 run execute 会因 existingMeta 存在
+  // 直接复用带脏状态的旧 worktree（启动逻辑：meta 存在即复用，不查健康状态）
+  if (stageName === 'execute' && changeName) {
+    try {
+      const { WorktreeManager } = await import('./worktree.js')
+      const wm = new WorktreeManager({ cwd })
+      const meta = wm.getMeta(changeName)
+      if (meta) {
+        const cleanResult = wm.cleanup(changeName)
+        if (cleanResult.residual?.length > 0) {
+          console.warn(`⚠️  reset 清理 worktree 残留: ${cleanResult.residual.join('; ')}`)
+          console.warn(`   手动处理: sillyspec worktree cleanup ${changeName} --force`)
+        } else if (cleanResult.result === 'kept') {
+          console.log(`🔗 旧 worktree 保留 (${cleanResult.mode}: 外部隔离环境)`)
+        } else if (cleanResult.result !== 'skipped') {
+          console.log(`🧹 已清理旧 worktree (${cleanResult.result}, mode: ${cleanResult.mode})，下次 execute 将重建干净环境`)
+        }
+      }
+    } catch (e) {
+      console.warn(`⚠️  reset 清理 worktree 失败（不阻断 reset）: ${e.message}`)
+    }
+  }
   const defSteps = await getStageSteps(stageName, cwd, progress, platformOpts?.specRoot || null)
   progress.stages[stageName] = {
     status: 'in-progress',

package/src/stage-contract.js

@@ -391,10 +391,11 @@ function validateVerifyOutputs(cwd, changeName, context = {}) {
     return { ok: false, errors, warnings }
   }
 
-  // verify 阶段应该产出 verify-result.md（或类似报告）
+  // verify 阶段必须产出 verify-result.md —— 不存在则不能完成。
+  // 历史教训：AI 可能跳过报告直接 --done，导致"假完成"。此处提级为 error 强制阻断。
   const verifyResult = join(changeDir, 'verify-result.md')
   if (!existsSync(verifyResult)) {
-    warnings.push('verify-result.md 不存在（verify 阶段建议产出验证报告）')
+    errors.push(`verify-result.md 不存在 — verify 阶段必须产出验证报告才能完成（${verifyResult}）`)
   }
 
   // 确保核心规范文件仍然存在
@@ -415,6 +416,17 @@ function validateVerifyOutputs(cwd, changeName, context = {}) {
     const decisionIds = extractCurrentDecisionIds(decisions)
     warnMissingIds(warnings, decisionIds, verify, 'verify-result.md', 'decisions.md')
 
+    // ── FAIL 结论门控（适用于所有变更，不限风险等级）──
+    // verify-result.md 结论为 FAIL 时，verify 阶段不能 completed。
+    // 历史教训：CLI 曾不校验结论，AI 写 FAIL 后 verify 仍被标记完成并提示"验证通过可以归档"。
+    const conclusionLine = verify.match(/^##\s*结论\s*\n\s*(PASS(?:\s+WITH\s+NOTES)?|FAIL)/im)
+    const conclusionStr = conclusionLine ? conclusionLine[1].toUpperCase().replace(/\s+/g, ' ') : ''
+    if (conclusionStr === 'FAIL') {
+      errors.push('verify-result.md 结论为 FAIL — 验证未通过，不能标记 verify 完成；请修复后重新运行验证')
+    } else if (!conclusionStr) {
+      warnings.push('verify-result.md 未识别到「## 结论」章节（应为 PASS / PASS WITH NOTES / FAIL）')
+    }
+
     // ── P0: Change Risk Gate — 核心功能缺少真实集成验证时 FAIL ──
     const changeRiskProfile = detectChangeRisk({
       designContent: readIfExists(join(changeDir, 'design.md')),

package/src/sync.js

@@ -12,6 +12,16 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from '
 import { join } from 'path';
 import { resolvePlatformSpecDir } from './progress.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;
@@ -201,7 +211,7 @@ export class SyncManager {
     let progressData;
     try {
       const { ProgressManager } = await import('./progress.js');
-      const pm = new ProgressManager({ specDir: resolvePlatformSpecDir(this.cwd) });
+      const pm = new ProgressManager({ specDir: safePlatformSpecDir(this.cwd) });
       progressData = await pm.read(this.cwd, changeName);
     } catch (err) {
       console.warn(`[sync] 读取 progress 失败 (${changeName}): ${err.message}`);
@@ -226,7 +236,7 @@ export class SyncManager {
     // 更新 platform_last_sync
     try {
       const { ProgressManager } = await import('./progress.js');
-      const pm = new ProgressManager({ specDir: resolvePlatformSpecDir(this.cwd) });
+      const pm = new ProgressManager({ specDir: safePlatformSpecDir(this.cwd) });
       await pm._updatePlatformLastSync(this.cwd, changeName);
     } catch (err) {
       console.warn(`[sync] 更新 platform_last_sync 失败: ${err.message}`);
@@ -327,7 +337,7 @@ export class SyncManager {
     // 更新本地 approvals 表
     try {
       const { ProgressManager } = await import('./progress.js');
-      const pm = new ProgressManager({ specDir: resolvePlatformSpecDir(this.cwd) });
+      const pm = new ProgressManager({ specDir: safePlatformSpecDir(this.cwd) });
       await pm._updateApprovalStatus(this.cwd, changeName, result.status, result.reason);
     } catch (err) {
       console.warn(`[sync] 更新本地审批状态失败: ${err.message}`);

package/src/worktree.js

@@ -73,6 +73,17 @@ function parseJSON(raw) {
   try { return JSON.parse(raw); } catch { return null; }
 }
 
+/**
+ * 跨平台同步等待（cleanup 重试退避用）
+ * 不依赖外部 sleep 命令——Windows cmd.exe 无 sleep；当 Git for Windows 未把 usr/bin 加入
+ * PATH 时，execSync('sleep 0.5') 会抛错并从 catch 块冒泡，直接中断整个 cleanup()。
+ * 改用 busy-wait 规避，保证 retry 之间真有间隔且不依赖环境。
+ */
+function sleepMs(ms) {
+  const end = Date.now() + ms;
+  while (Date.now() < end) { /* spin */ }
+}
+
 function computeBaselineHash(cwd) {
   // 排除 .sillyspec/ 元数据目录，避免 brainstorm/plan 阶段修改的蓝图文件污染 baseline
   const exclude = '-- . ":(exclude).sillyspec/"';
@@ -198,7 +209,7 @@ export class WorktreeManager {
     if (isolation.inSubmodule) {
       throw new Error(
         '当前目录在 git submodule 内，SillySpec worktree 不支持在 submodule 中创建。' +
-        '\n请在主仓库中执行，或使用 --no-worktree 跳过隔离。'
+        '\n请在主仓库根目录执行 execute。'
       );
     }
     if (isolation.inWorktree) {
@@ -237,6 +248,10 @@ export class WorktreeManager {
       if (!this.getMeta(name)) {
         console.log(`⚠️  检测到幽灵 worktree 目录（无 meta.json），自动清理...`);
         try { rmSync(worktreePath, { recursive: true, force: true }); } catch {}
+        // 同步清理 git worktree 注册 + 残留分支，否则目录虽删但 git 内部状态未清，
+        // 后续 git worktree add 会因「worktree 已注册」或「分支已存在」失败
+        try { gitQuiet(this.cwd, 'worktree prune'); } catch {}
+        try { gitQuiet(this.cwd, `branch -D ${branch}`); } catch {}
       } else {
         throw new Error(`worktree already exists: ${name}. Run cleanup first.`);
       }
@@ -269,7 +284,7 @@ export class WorktreeManager {
     } catch (e) {
       const check = isGitWorktreeSupported(this.cwd);
       if (!check.supported) {
-        throw new Error(`git worktree add 失败: ${e.stderr || e.message}\n\n${check.reason ? `原因: ${check.reason}` : ''}\n建议: 使用 --no-worktree 标志跳过隔离，或升级 git 到 >= 2.15`);
+        throw new Error(`git worktree add 失败: ${e.stderr || e.message}\n\n${check.reason ? `原因: ${check.reason}` : ''}\n建议: 升级 git 到 >= 2.15；或运行 \`sillyspec worktree doctor --fix\` 检查 worktree 状态。`);
       }
       // sandbox/permission fallback: 降级为 in-place + baseline protection
       console.log(`⚠️  git worktree add 失败（可能是沙箱权限限制），降级为 in-place 模式 + baseline protection`);
@@ -546,7 +561,10 @@ export class WorktreeManager {
    * 三重清理：git worktree 注册 + worktree 目录 + meta 目录。
    * @param {string} changeName
    * @param {{ force?: boolean, maxRetries?: number }} opts
-   * @returns {{ result: 'cleaned'|'force-cleaned'|'skipped'|'kept', mode: string|null, details: string[] }}
+   * @returns {{ result: 'cleaned'|'force-cleaned'|'skipped'|'kept'|'partial', mode: string|null, details: string[], residual: string[] }}
+   *   result 取值：cleaned=git remove 成功；force-cleaned=git remove 失败但 fallback 清理完成；
+   *   partial=有残留（目录/meta/git 注册未清）；skipped=无需清理；kept=native-worktree 保留。
+   *   residual：未清干净的路径/引用列表（空数组表示干净）。
    */
   cleanup(changeName, { force = false, maxRetries = 3 } = {}) {
     const name = validateChangeName(changeName);
@@ -561,22 +579,20 @@ export class WorktreeManager {
     }
 
     const mode = meta?.mode || 'worktree';
+    // in-place 模式：worktreePath === 主工作区，绝对禁止删除目录本身，但 meta 目录仍应清理
+    // （否则永久残留）。native-worktree：外部隔离环境，整体跳过。
+    const isInPlace = mode === 'in-place-fallback';
 
-    // 安全检查：只有 SillySpec 创建的 worktree 才允许删除
-    if (!force) {
-      if (mode === 'native-worktree') {
-        return { result: 'kept', mode, details: ['native-worktree: 外部隔离环境，跳过清理'] };
-      }
-      if (mode === 'in-place-fallback') {
-        return { result: 'skipped', mode, details: ['in-place-fallback: 无隔离目录，跳过清理'] };
-      }
+    // 安全检查：native-worktree 是外部隔离环境，非 force 不碰
+    if (!force && mode === 'native-worktree') {
+      return { result: 'kept', mode, details: ['native-worktree: 外部隔离环境，跳过清理'], residual: [] };
     }
 
     const branch = (meta && meta.branch) || BRANCH_PREFIX + name;
 
-    // 1. git worktree remove（带 retry）
+    // 1. git worktree remove（带 retry）—— in-place 跳过：无 git worktree 注册，且 worktreePath 即主工作区
     let gitRemoveOk = false;
-    if (existsSync(worktreePath)) {
+    if (!isInPlace && existsSync(worktreePath)) {
       for (let attempt = 1; attempt <= maxRetries; attempt++) {
         try {
           git(this.cwd, `worktree remove ${worktreePath} --force`);
@@ -586,15 +602,15 @@ export class WorktreeManager {
         } catch (e) {
           details.push(`git worktree remove attempt ${attempt}/${maxRetries} failed: ${e.message}`);
           if (attempt < maxRetries) {
-            // 短暂等待后重试
-            execSync('sleep 0.5', { stdio: 'pipe' });
+            // 短暂等待后重试（跨平台 busy-wait，见 sleepMs）
+            sleepMs(500);
           }
         }
       }
     }
 
-    // 2. fallback: 确保 worktree 目录已删除
-    if (existsSync(worktreePath)) {
+    // 2. fallback: 确保 worktree 目录已删除（in-place 跳过——worktreePath 是主工作区）
+    if (!isInPlace && existsSync(worktreePath)) {
       try {
         rmSync(worktreePath, { recursive: true, force: true });
         details.push('worktree directory force-removed (fallback)');
@@ -618,7 +634,7 @@ export class WorktreeManager {
       // 分支可能已被删除，幂等跳过
     }
 
-    // 5. 清除 meta 目录
+    // 5. 清除 meta 目录（in-place 模式也执行——这是 in-place meta 残留的修复点）
     if (existsSync(metaDir)) {
       try {
         rmSync(metaDir, { recursive: true, force: true });
@@ -628,18 +644,27 @@ export class WorktreeManager {
       }
     }
 
-    // 6. 最终验证：确认三重清理完成
+    // 6. 最终验证：确认清理完成（in-place 模式 worktreePath=主工作区，不纳入残留检查）
     const residual = [];
-    if (existsSync(worktreePath)) residual.push(`worktree dir: ${worktreePath}`);
+    if (!isInPlace && existsSync(worktreePath)) residual.push(`worktree dir: ${worktreePath}`);
     if (existsSync(metaDir)) residual.push(`meta dir: ${metaDir}`);
-    if (gitQuiet(this.cwd, `worktree list`)?.includes(worktreePath)) {
+    if (!isInPlace && gitQuiet(this.cwd, `worktree list`)?.includes(worktreePath)) {
       residual.push('git worktree list still references this worktree');
     }
     if (residual.length > 0) {
       details.push(`⚠️ 残留: ${residual.join('; ')}`);
     }
 
-    return { result: gitRemoveOk ? 'cleaned' : 'force-cleaned', mode, details };
+    // result：有残留→partial；in-place（无隔离目录可删，只清了 meta）→cleaned；否则按 git remove 成败
+    let result;
+    if (residual.length > 0) {
+      result = 'partial';
+    } else if (isInPlace) {
+      result = 'cleaned';
+    } else {
+      result = gitRemoveOk ? 'cleaned' : 'force-cleaned';
+    }
+    return { result, mode, details, residual };
   }
 
   /**
@@ -680,8 +705,10 @@ export class WorktreeManager {
       for (const entry of entries) {
         const lines = entry.split('\n');
         const wtPath = lines.find(l => l.startsWith('worktree '))?.replace('worktree ', '');
+        // git 2.20+ porcelain 在目录缺失时输出 `missing` 行；作为 existsSync 的权威交叉验证
+        const missing = lines.some(l => l === 'missing');
         if (wtPath && wtPath !== this.cwd) { // 排除主工作区
-          gitWorktreeList.push({ path: wtPath, raw: entry });
+          gitWorktreeList.push({ path: wtPath, missing, raw: entry });
         }
       }
     } catch {
@@ -693,12 +720,25 @@ export class WorktreeManager {
     const metaNames = new Set(metaEntries.map(m => m.changeName));
 
     // 3. 检查 git worktree list 中的孤儿条目
+    // ⚠️ 只在 git 自己标记 missing 时自动 prune。目录不可见但 git 未标记 missing 的
+    // 情况（平台模式/容器路径不一致、符号链接、Windows 路径格式、旧 git 无 missing 标记）
+    // 只告警不自动 prune —— existsSync 在这些场景会误判，自动 prune 会杀死实际在用的
+    // worktree（sillyspec-worktree-platform-mode-bug）。git 内部状态是 worktree 生命周期的
+    // 权威来源，用它做 prune 前提可杜绝误杀。
     for (const wt of gitWorktreeList) {
       if (!existsSync(wt.path)) {
         const name = this._pathToChangeName(wt.path);
-        issues.push({ type: 'orphan-git-entry', name: name || wt.path, detail: `git worktree 引用存在但目录不存在: ${wt.path}`, fixable: true });
-        if (fix) {
-          try { gitQuiet(this.cwd, 'worktree prune'); fixed.push(`pruned orphan: ${wt.path}`); } catch { unfixable.push(`prune failed for: ${wt.path}`); }
+        if (wt.missing === true) {
+          // git 明确标记目录缺失（git 2.20+）→ 真 orphan，prune 安全
+          issues.push({ type: 'orphan-git-entry', name: name || wt.path, detail: `git worktree 标记 missing: ${wt.path}`, fixable: true });
+          if (fix) {
+            try { gitQuiet(this.cwd, 'worktree prune'); fixed.push(`pruned orphan: ${wt.path}`); } catch { unfixable.push(`prune failed for: ${wt.path}`); }
+          }
+        } else {
+          // 目录不可见但 git 未标记 missing → 可能 existsSync 误判，保守不自动 prune
+          issues.push({ type: 'orphan-git-entry', name: name || wt.path,
+            detail: `git worktree 引用 ${wt.path} 目录不可见但 git 未标记 missing——可能路径/权限导致误判，未自动 prune（避免误杀在用的 worktree）。确认废弃后手动: git worktree prune`,
+            fixable: false });
         }
       }
     }
@@ -761,9 +801,10 @@ export class WorktreeManager {
         if (meta && meta.createdAt) {
           const ageMs = Date.now() - new Date(meta.createdAt).getTime();
           const ageHours = ageMs / (1000 * 60 * 60);
+          const staleFixable = meta.mode !== 'native-worktree';
           if (ageHours > staleHours) {
-            issues.push({ type: 'stale', name, detail: `worktree 已存在 ${Math.round(ageHours)} 小时（超过 ${staleHours}h 阈值）`, fixable: true });
-            if (fix && meta.mode !== 'native-worktree') {
+            issues.push({ type: 'stale', name, detail: `worktree 已存在 ${Math.round(ageHours)} 小时（超过 ${staleHours}h 阈值）${staleFixable ? '' : '（native-worktree 外部环境，不可自动清理）'}`, fixable: staleFixable });
+            if (fix && staleFixable) {
               try {
                 const result = this.cleanup(name);
                 if (result.result === 'cleaned' || result.result === 'force-cleaned') {