sillyspec 3.18.3 → 3.18.4

package/src/init.js

@@ -108,12 +108,39 @@ async function doInstall(projectDir, tools, subprojects = [], specDir = null) {
   // projectDir: 源码项目根目录（用于工具检测、指令注入、.gitignore）
   const spec = specDir || join(projectDir, '.sillyspec');
 
-  // 外部 specDir 时清理旧版本残留的 cwd/.sillyspec/（防止源码污染）
+  // 外部 specDir 时清理旧版本残留的 cwd/.sillyspec/（防止源码污染）。
+  // ⚠️ 必须保护真实资产：若本地 .sillyspec 含 changes/（非空）、projects/（非空）
+  // 或 sillyspec.db（进度库），说明该项目本身就用 SillySpec 管理，整体删除会丢资产。
+  // 此时只清运行时残留，拒绝整删；确无资产时才视为旧残留清理。
   const legacyDir = join(projectDir, '.sillyspec');
   if (specDir && existsSync(legacyDir)) {
-    try { rmSync(legacyDir, { recursive: true, force: true }) } catch {}
-    if (!existsSync(legacyDir)) console.log('🧹 已清理旧版本残留的源码 .sillyspec/ 目录');
-    else console.error('⚠️ 清理残留 .sillyspec/ 失败');
+    let hasChanges = false;
+    try {
+      const changesDir = join(legacyDir, 'changes');
+      if (existsSync(changesDir)) hasChanges = readdirSync(changesDir).length > 0;
+    } catch {}
+    let hasProjects = false;
+    try {
+      const projectsDir = join(legacyDir, 'projects');
+      if (existsSync(projectsDir)) hasProjects = readdirSync(projectsDir).length > 0;
+    } catch {}
+    const hasDb = existsSync(join(legacyDir, 'sillyspec.db'));
+
+    if (hasChanges || hasProjects || hasDb) {
+      // 真实资产存在：拒绝整体删除，仅清理运行时残留
+      console.error('❌ [sillyspec] 拒绝删除源码目录的 .sillyspec/：检测到真实资产（changes/、projects/ 或 sillyspec.db）。');
+      console.error('   该项目似乎本身就用 SillySpec 管理。如需改用外部 spec 目录，请先手动迁移/备份。');
+      console.error('   本次仅清理运行时残留（.runtime/、local.yaml、codebase/）。');
+      for (const residue of ['.runtime', 'local.yaml', 'codebase']) {
+        const p = join(legacyDir, residue);
+        if (existsSync(p)) { try { rmSync(p, { recursive: true, force: true }) } catch {} }
+      }
+    } else {
+      // 无真实资产：确属旧版本残留，安全删除
+      try { rmSync(legacyDir, { recursive: true, force: true }) } catch {}
+      if (!existsSync(legacyDir)) console.log('🧹 已清理旧版本残留的源码 .sillyspec/ 目录');
+      else console.error('⚠️ 清理残留 .sillyspec/ 失败');
+    }
   }
 
   // 创建基础目录

package/src/run.js

@@ -1148,11 +1148,32 @@ export async function runCommand(args, cwd, specDir = null) {
   // runCommand 后续所有 .sillyspec/ 操作必须用 specBase
   const specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
 
-  // 平台模式：清理旧版本残留的 cwd/.sillyspec/（防止源码污染）
+  // 平台模式：清理旧版本残留的 cwd/.sillyspec/（防止源码污染）。
+  // ⚠️ 同 init.js：必须保护真实资产（changes/、projects/、sillyspec.db）。
   if (platformOpts.specRoot) {
     const legacyDir = join(cwd, '.sillyspec')
     if (existsSync(legacyDir)) {
-      try { rmSync(legacyDir, { recursive: true, force: true }) } catch {}
+      let hasChanges = false;
+      try {
+        const cd = join(legacyDir, 'changes');
+        if (existsSync(cd)) hasChanges = readdirSync(cd).length > 0;
+      } catch {}
+      let hasProjects = false;
+      try {
+        const pd = join(legacyDir, 'projects');
+        if (existsSync(pd)) hasProjects = readdirSync(pd).length > 0;
+      } catch {}
+      const hasDb = existsSync(join(legacyDir, 'sillyspec.db'));
+
+      if (hasChanges || hasProjects || hasDb) {
+        console.error('❌ [sillyspec] 拒绝删除源码目录的 .sillyspec/：检测到真实资产。仅清理运行时残留。');
+        for (const residue of ['.runtime', 'local.yaml', 'codebase']) {
+          const p = join(legacyDir, residue);
+          if (existsSync(p)) { try { rmSync(p, { recursive: true, force: true }) } catch {} }
+        }
+      } else {
+        try { rmSync(legacyDir, { recursive: true, force: true }) } catch {}
+      }
     }
   }
 
@@ -1943,12 +1964,38 @@ async function continueStep(pm, progress, stageName, cwd, answer, options = {})
     stageData.completedAt = now
     await pm._write(cwd, progress, changeName)
     console.log(`\n✅ ${stageName} 阶段已完成（${stageData.steps.length}/${stageData.steps.length} 步）`)
+    // ── execute 阶段完成时条件性清理 worktree ──
+    if (stageName === 'execute' && changeName) {
+      try {
+        const { WorktreeManager } = await import('./worktree.js');
+        const wm = new WorktreeManager({ cwd });
+        const meta = wm.getMeta(changeName);
+        if (!meta) {
+          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 {
+          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);
+            console.log(`🔗 Worktree: ${cleanResult.result}`);
+          }
+        }
+      } catch (e) {
+        console.warn(`🔗 Worktree: check failed — ${e.message}`);
+      }
+    }
     return { stageCompleted: true, currentIdx, nextPendingIdx: -1 }
   }
 
   // 输出下一步
-  if (nextPendingIdx !== -1 && defSteps) {
-    console.log('')
+    if (nextPendingIdx !== -1 && defSteps) {
+      console.log('')
     await outputStep(stageName, nextPendingIdx, defSteps, cwd, changeName, progress.project || null, platformOpts, answer)
   } else if (nextWaitingIdx !== -1 && defSteps) {
     // 下一个步骤也在等待状态
@@ -2517,6 +2564,42 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
       console.log(`\n⚠️ 阶段校验跳过：${actualTotal} 步中仅 ${actualCompleted} 步标记为已完成，可能存在状态不同步。如确认阶段已完成，请运行 --status 确认。`)
     }
 
+    // ── execute 阶段完成时条件性清理 worktree（不依赖 AI agent 的完成确认步骤）──
+    if (stageName === 'execute' && changeName) {
+      try {
+        const { WorktreeManager } = await import('./worktree.js');
+        const wm = new WorktreeManager({ cwd });
+        const meta = wm.getMeta(changeName);
+        if (!meta) {
+          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 {
+          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}`);
+                }
+              }
+            }
+          }
+        }
+      } catch (e) {
+        console.warn(`🔗 Worktree: check failed — ${e.message}`);
+      }
+    }
+
     return { stageCompleted: true, currentIdx, nextPendingIdx: -1 }
   }
 

package/src/stages/execute.js

@@ -406,6 +406,48 @@ function parseWavesFromPlan(planContent) {
  * 为 Wave 生成 prompt（强制子代理执行）
  */
 function buildWavePrompt(wave, waveIndex, changeDir, worktreePath) {
+  // ── Contract Matrix：检查是否有 provider/consumer 契约需要注入 ──
+  let contractInjection = ''
+  if (changeDir) {
+    try {
+      const { buildContractMatrix, buildConsumerInjection } = require('../contract-matrix.js')
+      const planFile = path.join(changeDir, 'plan.md')
+      if (existsSync(planFile)) {
+        const planContent = readFileSync(planFile, 'utf8')
+        const contracts = buildContractMatrix(planContent, changeDir)
+        if (contracts.length > 0) {
+          // 收集本 wave 所有 task 的注入内容
+          const waveTasks = wave.tasks.map((t, ti) => {
+            const num = String(t.index || (ti + 1)).padStart(2, '0')
+            return `task-${num}`
+          })
+          const relevantContracts = contracts.filter(c => waveTasks.includes(c.consumer))
+          if (relevantContracts.length > 0) {
+            contractInjection = `
+### API Contract Matrix
+本 Wave 存在前端/后端跨 task 契约：
+${relevantContracts.map(c => `- **${c.consumer}** 消费 **${c.provider}** 产出的 API`).join('\n')}
+`
+            // 为每个 consumer task 生成详细注入
+            for (const taskName of waveTasks) {
+              const injection = buildConsumerInjection(changeDir, join(changeDir, '..', '..'), taskName, contracts)
+              if (injection) {
+                contractInjection += `
+### 子代理 ${taskName} 的契约注入
+为 ${taskName} 启动子代理时，在子代理 prompt 末尾追加以下内容：
+
+<contract-injection>
+${injection}
+</contract-injection>
+`
+              }
+            }
+          }
+        }
+      }
+    } catch {}
+  }
+
   // 构建任务摘要（不再内联完整蓝图，减少上下文污染）
   const taskSummary = wave.tasks.map((t, ti) => {
     const taskNum = String(t.index || (ti + 1)).padStart(2, '0')
@@ -476,7 +518,7 @@ ${taskSummary}
    - 🔥 热上下文：design.md 编码铁律 + 当前 Wave 任务（必须加载）
    - 🌡️ 温上下文：CONVENTIONS.md + ARCHITECTURE.md（需要时加载）
    - ❄️ 冷上下文：其他变更的 design.md、历史 plan.md（不要主动加载，除非明确需要）
-
+${contractInjection}
 ### 本 Wave 任务
 ${taskList}
 
@@ -493,7 +535,11 @@ ${taskList}
 5. 遇到 BLOCKED → 记录原因，选择：重试/跳过/停止
 
 ### 完成后
-运行 sillyspec run execute --done --input "用户原始反馈" --output "Wave ${waveIndex} 结果摘要"`
+1. 为每个后端 router task，扫描变更文件提取 API 端点 artifact：
+   - 在变更文件中搜索所有 router 注册路径（@router.get/post/put/delete）
+   - 将端点清单写入 .sillyspec/.runtime/contract-artifacts/<task-name>/endpoints.json
+   - 格式: { "task": "task-XX", "type": "backend_endpoints", "endpoints": [{ "method": "GET", "path": "/api/ppm/xxx" }] }
+2. 运行 sillyspec run execute --done --input "用户原始反馈" --output "Wave ${waveIndex} 结果摘要"`
 }
 
 

package/src/stages/verify.js

@@ -134,6 +134,31 @@ grep -rl "<关键词>" <源码目录>/ --include="*.java" --include="*.js" --inc
 5. 任意 D-xxx@vN 无下游覆盖时标记为 ⚠️ 决策未闭环
 6. 任意 P0/P1 unresolved/blocking 决策标记为 FAIL blocker
 
+**探针 5：API Contract Parity Check（跨前后端契约对账）**
+此探针仅在以下条件满足时执行：
+- 存在 \.sillyspec/.runtime/contract-artifacts/ 目录（说明 execute 阶段生成了 endpoint artifact）
+- 或者项目同时有 backend/ 和 frontend/ 目录
+
+执行步骤：
+1. 收集所有 provider endpoint artifacts：
+   - 读取 .sillyspec/.runtime/contract-artifacts/*/endpoints.json
+   - 汇总为 backend 端点清单
+2. 扫描前端 API 调用：
+   - 在 frontend/ 目录中搜索 apiFetch/request/axios/fetch 调用
+   - 提取所有 API 路径（归一化动态参数为 {param}）
+3. Diff 对账：
+   - 前端调用路径在 backend 端点清单中找不到 → **❌ Missing backend endpoint**（FAIL blocker）
+   - backend 端点在前端无调用 → ⚠️ Unused backend endpoint（warning，不阻断）
+4. 输出对账结果表格：
+   \
+\
+   | 状态 | 前端调用 | 后端端点 | 文件 |
+   |---|---|---|---|
+   | ❌ missing | GET /api/ppm/project-plan/{param}/plan-nodes | — | frontend/src/lib/ppm/plan.ts |
+\
+\
+   如果发现 Missing backend endpoint，必须在验证报告中标记为 ❌ contract gap。
+
 ### 探针结果处理
 - 将四个探针的结果汇总为「探针报告」
 - 如果探针发现问题（未实现标记、关键词缺失、测试缺失、决策未闭环），在最终验证报告中明确标注

package/src/worktree.js

@@ -239,6 +239,8 @@ export class WorktreeManager {
     }
 
     // 5.5 自动同步远程最新代码（防止 worktree 基于过时的 commit）
+    let syncStatus = 'ok';
+    let syncError = null;
     try {
       // 先 fetch origin
       gitQuiet(worktreePath, 'fetch origin');
@@ -262,8 +264,10 @@ export class WorktreeManager {
           }
         }
       }
-    } catch {
- // fetch/merge 失败不影响 worktree 创建，只记录警告
+    } catch (e) {
+      syncStatus = 'failed';
+      syncError = e.message || String(e);
+      console.warn(`⚠️  worktree 远程同步失败：${syncError}`);
     }
 
     // 5.6 Dirty baseline overlay：将主工作区未提交变更同步到 worktree
@@ -290,6 +294,8 @@ export class WorktreeManager {
       baselineFiles,
       baselineCommit,
       baselineHash,
+      syncStatus,
+      ...(syncError ? { syncError } : {}),
     };
 
     const metaPath = join(worktreePath, META_FILE);
@@ -412,18 +418,22 @@ export class WorktreeManager {
 
   /**
    * 清理 worktree（仅限 SillySpec 创建的临时 worktree）
+   * 幂等：重复调用不报错。
+   * 三重清理：git worktree 注册 + worktree 目录 + meta 目录。
    * @param {string} changeName
-   * @param {{ force?: boolean }} opts - force: 跳过 mode 安检（仅用于 worktree 目录本身）
-   * @throws {Error} worktree 不存在、不允许删除
-   * @returns {{ result: 'cleaned'|'skipped'|'kept', mode: string }}
+   * @param {{ force?: boolean, maxRetries?: number }} opts
+   * @returns {{ result: 'cleaned'|'force-cleaned'|'skipped'|'kept', mode: string|null, details: string[] }}
    */
-  cleanup(changeName, { force = false } = {}) {
+  cleanup(changeName, { force = false, maxRetries = 3 } = {}) {
     const name = validateChangeName(changeName);
     const meta = this.getMeta(name);
     const worktreePath = this.getWorktreePath(name);
+    const metaDir = join(this.worktreeBase, name);
+    const details = [];
 
-    if (!meta && !existsSync(worktreePath)) {
-      return { result: 'skipped', mode: null };
+    // 幂等：什么都不存在 → 直接跳过
+    if (!meta && !existsSync(worktreePath) && !existsSync(metaDir)) {
+      return { result: 'skipped', mode: null, details };
     }
 
     const mode = meta?.mode || 'worktree';
@@ -431,50 +441,269 @@ export class WorktreeManager {
     // 安全检查：只有 SillySpec 创建的 worktree 才允许删除
     if (!force) {
       if (mode === 'native-worktree') {
-        throw new Error(
-          `当前 worktree 是外部/原生隔离环境（mode: native-worktree），SillySpec 不允许删除。\n` +
-          `此 worktree 不是由 SillySpec 创建的，请手动管理。\n` +
-          `如需强制清理，使用 --force 标志。`
-        );
+        return { result: 'kept', mode, details: ['native-worktree: 外部隔离环境，跳过清理'] };
       }
       if (mode === 'in-place-fallback') {
-        return { result: 'skipped', mode };
+        return { result: 'skipped', mode, details: ['in-place-fallback: 无隔离目录，跳过清理'] };
       }
     }
 
-    // 1. 尝试 git worktree remove
-    let gitRemoveOk = true;
-    try {
-      git(this.cwd, `worktree remove ${worktreePath} --force`);
-    } catch (e) {
-      gitRemoveOk = false;
-    }
     const branch = (meta && meta.branch) || BRANCH_PREFIX + name;
 
-    // 2. 确保目录已删除
-    try {
-      if (existsSync(worktreePath)) {
+    // 1. git worktree remove（带 retry）
+    let gitRemoveOk = false;
+    if (existsSync(worktreePath)) {
+      for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        try {
+          git(this.cwd, `worktree remove ${worktreePath} --force`);
+          gitRemoveOk = true;
+          details.push(`git worktree remove succeeded (attempt ${attempt})`);
+          break;
+        } catch (e) {
+          details.push(`git worktree remove attempt ${attempt}/${maxRetries} failed: ${e.message}`);
+          if (attempt < maxRetries) {
+            // 短暂等待后重试
+            execSync('sleep 0.5', { stdio: 'pipe' });
+          }
+        }
+      }
+    }
+
+    // 2. fallback: 确保 worktree 目录已删除
+    if (existsSync(worktreePath)) {
+      try {
         rmSync(worktreePath, { recursive: true, force: true });
+        details.push('worktree directory force-removed (fallback)');
+      } catch (e) {
+        details.push(`worktree directory force-remove failed: ${e.message}`);
       }
-    } catch (e) {
-      throw new Error(`清理 worktree 目录失败: ${e.message}`);
     }
 
-    // 3. 删除分支（忽略分支不存在的错误）
-    gitQuiet(this.cwd, `branch -D ${branch}`);
+    // 3. git worktree prune（清理 git 内部注册信息）
+    try {
+      gitQuiet(this.cwd, 'worktree prune');
+    } catch {
+      // prune 失败不阻断
+    }
 
-    // 4. 确保目录已删除
-    if (existsSync(worktreePath)) {
-      rmSync(worktreePath, { recursive: true, force: true });
+    // 4. 删除分支（忽略分支不存在的错误）
+    try {
+      gitQuiet(this.cwd, `branch -D ${branch}`);
+      details.push('branch deleted');
+    } catch {
+      // 分支可能已被删除，幂等跳过
     }
 
-    // 5. 清除 meta 目录（如果 worktree 目录在 worktreeBase 下）
-    const metaDir = join(this.worktreeBase, name);
+    // 5. 清除 meta 目录
     if (existsSync(metaDir)) {
-      rmSync(metaDir, { recursive: true, force: true });
+      try {
+        rmSync(metaDir, { recursive: true, force: true });
+        details.push('meta directory cleaned');
+      } catch (e) {
+        details.push(`meta directory cleanup failed: ${e.message}`);
+      }
+    }
+
+    // 6. 最终验证：确认三重清理完成
+    const residual = [];
+    if (existsSync(worktreePath)) residual.push(`worktree dir: ${worktreePath}`);
+    if (existsSync(metaDir)) residual.push(`meta dir: ${metaDir}`);
+    if (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 };
+  }
+
+  /**
+   * worktree 健康检查 + 可选修复
+   * 检查项：
+   * - git worktree list 中的孤儿条目（目录不存在）
+   * - worktree 目录存在但 git 不认识
+   * - meta 存在但 worktree 目录不存在
+   * - worktree 目录存在但 meta 不存在（幽灵目录）
+   * - SillySpec 分支残留（sillyspec/* 但无对应 meta）
+   * - 超过指定小时的过期 worktree
+   *
+   * @param {{ fix?: boolean, staleHours?: number }} opts
+   * @returns {{ issues: Array<{ type: string, name: string, detail: string, fixable: boolean }>, fixed: string[], unfixable: string[] }}
+   */
+  doctor({ fix = false, staleHours = 24 } = {}) {
+    const issues = [];
+    const fixed = [];
+    const unfixable = [];
+
+    // 1. 列出 git worktree list 中的条目
+    let gitWorktreeList = [];
+    try {
+      const raw = execSync(`git worktree list --porcelain`, { cwd: this.cwd, encoding: 'utf8', stdio: ['pipe','pipe','pipe'] });
+      const entries = raw.split(/\n\n/).filter(Boolean);
+      for (const entry of entries) {
+        const lines = entry.split('\n');
+        const wtPath = lines.find(l => l.startsWith('worktree '))?.replace('worktree ', '');
+        if (wtPath && wtPath !== this.cwd) { // 排除主工作区
+          gitWorktreeList.push({ path: wtPath, raw: entry });
+        }
+      }
+    } catch {
+      // git worktree 不可用，跳过
+    }
+
+    // 2. 列出 SillySpec meta 条目
+    const metaEntries = this.list();
+    const metaNames = new Set(metaEntries.map(m => m.changeName));
+
+    // 3. 检查 git worktree list 中的孤儿条目
+    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}`); }
+        }
+      }
+    }
+
+    // 4. 扫描 worktreeBase 目录，检查幽灵目录和孤儿 meta
+    if (existsSync(this.worktreeBase)) {
+      const entries = readdirSync(this.worktreeBase, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        const name = entry.name;
+        const dirPath = join(this.worktreeBase, name);
+        const hasMeta = existsSync(join(dirPath, META_FILE));
+        const meta = hasMeta ? this.getMeta(name) : null;
+
+        // meta 存在但 worktree 目录不存在
+        if (meta && meta.worktreePath && !existsSync(meta.worktreePath)) {
+          issues.push({ type: 'meta-no-dir', name, detail: `meta 存在但 worktree 目录不存在: ${meta.worktreePath}`, fixable: true });
+          if (fix) {
+            try { rmSync(dirPath, { recursive: true, force: true }); fixed.push(`cleaned orphan meta: ${name}`); } catch { unfixable.push(`cleanup failed for: ${name}`); }
+          }
+        }
+
+        // worktree 目录存在但 meta 不存在（幽灵目录）
+        if (!hasMeta && existsSync(dirPath)) {
+          // 可能是 in-place 模式的 meta-only 目录，或者真正的幽灵
+          const files = readdirSync(dirPath);
+          if (files.length === 0 || (files.length === 1 && files[0] === META_FILE)) {
+            issues.push({ type: 'ghost-dir', name, detail: `空目录/幽灵目录: ${dirPath}`, fixable: true });
+            if (fix) {
+              try { rmSync(dirPath, { recursive: true, force: true }); fixed.push(`removed ghost dir: ${name}`); } catch { unfixable.push(`remove failed for: ${name}`); }
+            }
+          } else {
+            issues.push({ type: 'ghost-dir-with-files', name, detail: `目录存在但无 meta.json: ${dirPath} (含 ${files.length} 文件)`, fixable: false });
+          }
+        }
+
+        // 检查过期 worktree
+        if (meta && meta.createdAt) {
+          const ageMs = Date.now() - new Date(meta.createdAt).getTime();
+          const ageHours = ageMs / (1000 * 60 * 60);
+          if (ageHours > staleHours) {
+            issues.push({ type: 'stale', name, detail: `worktree 已存在 ${Math.round(ageHours)} 小时（超过 ${staleHours}h 阈值）`, fixable: true });
+            if (fix && meta.mode !== 'native-worktree') {
+              try {
+                const result = this.cleanup(name);
+                if (result.result === 'cleaned' || result.result === 'force-cleaned') {
+                  fixed.push(`cleaned stale: ${name}`);
+                } else {
+                  unfixable.push(`cleanup skipped: ${name}`);
+                }
+              } catch { unfixable.push(`cleanup failed: ${name}`); }
+            }
+          }
+        }
+      }
+    }
+
+    // 5. 检查 SillySpec 分支残留
+    try {
+      const branches = execSync(`git branch --list '${BRANCH_PREFIX}*'`, { cwd: this.cwd, encoding: 'utf8', stdio: ['pipe','pipe','pipe'] }).trim();
+      if (branches) {
+        for (const line of branches.split('\n').filter(Boolean)) {
+          const branch = line.replace(/^\*?\s+/, '').trim();
+          const name = branch.replace(BRANCH_PREFIX, '');
+          if (!metaNames.has(name)) {
+            issues.push({ type: 'orphan-branch', name, detail: `分支残留（无对应 meta）: ${branch}`, fixable: true });
+            if (fix) {
+              try { gitQuiet(this.cwd, `branch -D ${branch}`); fixed.push(`deleted orphan branch: ${branch}`); } catch { unfixable.push(`branch delete failed: ${branch}`); }
+            }
+          }
+        }
+      }
+    } catch {}
+
+    return { issues, fixed, unfixable };
+  }
+
+  /**
+   * 检查 worktree 是否有未 apply 到主工作区的变更
+   * @param {string} changeName
+   * @returns {{ hasChanges: boolean, changedFiles: string[], reason?: string }}
+   */
+  hasUnappliedChanges(changeName) {
+    const name = validateChangeName(changeName);
+    const meta = this.getMeta(name);
+    if (!meta) return { hasChanges: false, changedFiles: [], reason: 'no meta' };
+
+    const worktreePath = meta.worktreePath;
+    if (!worktreePath || !existsSync(worktreePath)) {
+      return { hasChanges: false, changedFiles: [], reason: 'worktree dir not found' };
+    }
+
+    // in-place 模式没有隔离目录，不算有未 apply 的变更
+    if (meta.mode === 'in-place-fallback') {
+      return { hasChanges: false, changedFiles: [], reason: 'in-place mode' };
+    }
+
+    const diffBase = meta.baselineCommit || meta.baseHash;
+    if (!diffBase) {
+      return { hasChanges: false, changedFiles: [], reason: 'no diff base' };
+    }
+
+    try {
+      // tracked 文件变更
+      const statusRaw = gitQuiet(worktreePath, `diff --name-status ${diffBase}`) || '';
+      const statusFiles = new Set();
+      if (statusRaw) {
+        for (const line of statusRaw.split('\n').filter(Boolean)) {
+          const parts = line.split('\t');
+          if (parts.length >= 2) statusFiles.add(parts[parts.length - 1]);
+          if (parts.length >= 3) statusFiles.add(parts[parts.length - 2]);
+        }
+      }
+
+      // untracked 文件
+      const untrackedRaw = gitQuiet(worktreePath, `ls-files --others --exclude-standard`) || '';
+      const untrackedFiles = untrackedRaw
+        ? untrackedRaw.split('\n').filter(Boolean).filter(f => !f.startsWith('.sillyspec/') && f !== 'meta.json')
+        : [];
+
+      const changedFiles = [...new Set([...statusFiles, ...untrackedFiles])];
+      return { hasChanges: changedFiles.length > 0, changedFiles };
+    } catch (e) {
+      // 检测失败时保守处理：视为有变更
+      return { hasChanges: true, changedFiles: [], reason: `diff failed: ${e.message}` };
     }
+  }
 
-    return { result: gitRemoveOk ? 'cleaned' : 'force-cleaned', mode };
+  /**
+   * 从 worktree 路径反推 changeName
+   * @private
+   */
+  _pathToChangeName(wtPath) {
+    try {
+      const resolved = resolve(wtPath);
+      const baseResolved = resolve(this.worktreeBase);
+      if (resolved.startsWith(baseResolved + '/')) {
+        return resolved.slice(baseResolved.length + 1);
+      }
+    } catch {}
+    return null;
   }
 
   /**