sillyspec 3.27.2 → 3.27.5

package/src/worktree-apply.js

@@ -329,7 +329,62 @@ function validateCrossRepoNoOp(ctx, projectRoot, changeName) {
  *   crossRepoValidated?: Array<{ repo: string, head: string }>
  * }}
  */
-export function applyWorktree(changeName, { cwd, checkOnly = false, merge = false, base = 'merge-base', ctx = null } = {}) {
+/**
+ * 主仓级互斥锁（坑 main-apply-no-mutex → 泛化 main-repo-no-mutex，2026-08-23 二批实证：
+ * 除 apply 外，cleanup（worktree 注册表/分支删除）、archive 收尾（目录 rename + 共享 index
+ * 的 git add + marker 删除）同样直接改主仓共享状态且零互斥——两会话并发操作互踩。泛化为
+ * withMainRepoLock：同一把主仓锁保护所有「写主仓的破坏性短操作」（apply / cleanup / archive
+ * 收尾）；verify 的长时间测试执行**不**上锁（读树为主，靠对账归属过滤与归因提示治误伤）。
+ *
+ * 锁粒度 = 主仓级（竞争资源是 main 工作区/.git 状态，非 change）：O_EXCL 文件锁复用
+ * quicklog 的 withFileLock（stale 偷锁 + rename 防 TOCTOU），锁内容写
+ * {pid, changeName, purpose, startedAt} 供超时报错展示持有者。staleMs 10min（大 diff/deps
+ * 可慢）；抢锁等待 60s 仍失败 → fail-closed 报错退出：写主仓操作并发互踩不可自动恢复，
+ * 宁可明确失败让人重试，不硬闯。只读路径（--check-only/status）不加锁。
+ */
+export async function withMainRepoLock(projectRoot, changeName, purpose, fn, opts = {}) {
+  const { withFileLock } = await import('./quicklog.js');
+  const lockPath = join(projectRoot, '.sillyspec', '.runtime', 'main-repo.lock');
+  const holder = JSON.stringify({ pid: process.pid, changeName, purpose: purpose || 'unknown', startedAt: new Date().toISOString() });
+  const { staleMs = 10 * 60 * 1000, retryMs = 200 } = opts;
+  // 等待时长可被 env 覆盖（测试与紧急调参用；opts.timeoutMs 显式传入仍最高优先）
+  const envTimeout = parseInt(process.env.SILLYSPEC_MAIN_REPO_LOCK_TIMEOUT_MS || '', 10);
+  const defaultTimeout = Number.isFinite(envTimeout) && envTimeout > 0 ? envTimeout : 60 * 1000;
+  const { timeoutMs = defaultTimeout } = opts;
+  // 进程退出兜底清锁：临界区内 process.exit（如 archiveChangeDirectory 的 guard exit(1)）不会走
+  // withFileLock 的 finally——不挂此钩子锁会残留挡他者直到 staleMs（10min）被偷。正常路径
+  // finally 先释放并注销钩子，钩子只在进程真正退出时执行，无双删竞态。
+  const onExit = () => { try { unlinkSync(lockPath) } catch {} };
+  process.on('exit', onExit);
+  try {
+    return await withFileLock(lockPath, fn, {
+      content: holder,
+      staleMs,
+      timeoutMs,
+      retryMs,
+    });
+  } catch (e) {
+    if (/文件锁超时/.test(String(e.message))) {
+      let holderInfo = '';
+      try {
+        const raw = readFileSync(lockPath, 'utf8');
+        try {
+          const h = JSON.parse(raw);
+          holderInfo = `（持有者: pid=${h.pid}, change=${h.changeName}, 操作=${h.purpose}, 始于 ${h.startedAt}）`;
+        } catch { holderInfo = `（持有者标识: ${raw.slice(0, 120)}）`; }
+      } catch { /* 锁文件已被释放（竞态窗口）→ 无持有者信息 */ }
+      throw new Error(
+        `主仓互斥锁被占用${holderInfo}：另一会话正在对主仓执行写操作（apply/cleanup/归档会写主仓工作区与 git 状态，并发互踩会互相清文件）。` +
+        `等它完成后重试即可；若确认持有进程已崩溃退出，删除锁文件后重试：${lockPath}`
+      );
+    }
+    throw e;
+  } finally {
+    process.removeListener('exit', onExit);
+  }
+}
+
+export function applyWorktree(changeName, { cwd, checkOnly = false, merge = false, base = 'merge-base', ctx = null, skipOverlap = false } = {}) {
   const projectRoot = cwd || process.cwd();
   const wm = new WorktreeManager({ cwd: projectRoot });
   const meta = wm.getMeta(changeName);
@@ -344,6 +399,7 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
     errors: [],
     merged: false,
     crossRepoValidated: [],
+    skippedOverlapFiles: [],
   };
 
   // --- 0. 跨仓 task no-op 校验（task-05 / D-009） ---
@@ -464,6 +520,20 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
     if (wtBlob === mainBlob) continue;
     result.hashMismatchFiles.push(f);
   }
+  // 派生产物基线漂移 advisory（坑 derived-artifact-stale-baseline，2026-08-23 实证：多 agent
+  // 并发仓中 worktree 旧基线生成的 api-types 被 apply 落地，把并行变更已合入主仓的新枚举刷掉，
+  // 一次 build 红）。hashMismatchFiles 此前只在 rescue 分类 / merge 冲突时冒头——语义级覆盖
+  // （旧内容文本可合 → --3way 静默成功）零提示。纯 warning 不阻断（生成器类变更的产物是合法
+  // 交付，是否重跑生成命令由 agent 判断）。
+  {
+    const derivedRisk = result.hashMismatchFiles.filter(f => changedFiles.includes(f));
+    if (derivedRisk.length > 0) {
+      result.warnings = (result.warnings || []).concat([
+        `${derivedRisk.length} 个变更文件在 worktree 基线后主仓已有新提交（并行变更可能已合入）：${derivedRisk.slice(0, 5).join(', ')}${derivedRisk.length > 5 ? ' 等' : ''}` +
+        `——若其中含生成产物（api-types/generated 等），本次 apply 可能以旧基线内容覆盖已合入的新内容；apply 后在新基线重跑生成命令（如 gen:types）再验证`
+      ]);
+    }
+  }
 
   // --- 4. 校验：变更文件 ⊆ 清单（无清单则跳过）---
   if (hasAllowList) {
@@ -482,8 +552,9 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
   // --- 4.6 显式 --merge：用户显式选择 git merge 兜底（主干已提交推进重叠时的三方合并） ---
   // 触发点从「4.5 baseline 漂移自动降级」改为「用户显式 --merge flag」（D-001 保留，触发方式变化）。
   // 用 --merge 时跳过未提交 dirty 拦截——merge 同样要求工作区相对干净，此处仅提示风险，真正失败由 applyByMerge 报告。
+  // keepConflicts:true——显式 --merge 冲突时保留现场供手工解决（不再直接 abort 丢上下文）。
   if (merge && !checkOnly) {
-    return applyByMerge(result, changeName, projectRoot, wm);
+    return applyByMerge(result, changeName, projectRoot, wm, { keepConflicts: true });
   }
 
   // --- 4.5 校验：主工作区「未提交」脏文件是否与本次变更重叠（overlap-only 拦截）---
@@ -518,6 +589,29 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
       )].filter(f => !f.startsWith('.sillyspec/') && f !== 'meta.json');
       const overlapDirty = dirtyFiles.filter(f => changedFiles.includes(f));
       if (overlapDirty.length > 0) {
+        // --skip-overlap（坑 apply-overlap-all-or-nothing，2026-08-23 实证：多 agent 并发仓主仓
+        // 常态有在途变更，overlap 整批拦截使 apply 基本不可用，rescue 手动 cp 又留混合状态）：
+        // 显式 opt-in 剔除重叠文件、应用干净子集。重叠文件留在 worktree——step8 非 force
+        // cleanup 被 hasUnappliedChanges 护栏拦住（主仓工作区逐字节降噪层只剔除已应用文件），
+        // 待主仓干净后重新 apply（此时只剩剩余文件）或人工裁决。
+        if (skipOverlap && !checkOnly) {
+          const skipSet = new Set(overlapDirty);
+          result.skippedOverlapFiles = overlapDirty.slice();
+          changedFiles = changedFiles.filter(f => !skipSet.has(f));
+          result.changedFiles = changedFiles;
+          result.deletedFiles = deletedFiles.filter(f => !skipSet.has(f));
+          result.hashMismatchFiles = (result.hashMismatchFiles || []).filter(f => !skipSet.has(f));
+          if (changedFiles.length === 0) {
+            result.errors.push(
+              `--skip-overlap：本次 ${overlapDirty.length} 个变更文件全部与主仓未提交改动重叠，无可应用子集：\n  ${overlapDirty.join('\n  ')}\n` +
+              `请先提交/stash 主仓改动后重试（不带 --skip-overlap）。`
+            );
+            return result;
+          }
+          result.warnings = (result.warnings || []).concat([
+            `--skip-overlap：跳过 ${overlapDirty.length} 个与主仓未提交改动重叠的文件（留在 worktree，未应用）：${overlapDirty.join(', ')}——待主仓提交/stash 后重新 apply 只应用剩余文件，或确认放弃后 cleanup --force`
+          ]);
+        } else {
         // 重叠拦截：只有与本次变更同文件的未提交改动才无法安全 apply（列重叠文件，非全部脏文件）
         const rescueDirty = computeRescueDirtyFiles(projectRoot);
         result.rescueCommands = generateRescueCommands({
@@ -531,6 +625,7 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
         result.errors.push(
           `主工作区以下未提交文件与本次 apply 的变更重叠，git apply 无法安全应用：\n  ${overlapDirty.join('\n  ')}\n` +
           `请先提交或暂存这些改动，再重新 apply：\n  git add -A && git commit -m "..."   或   git stash\n` +
+          `或应用非重叠部分（重叠文件留在 worktree，主仓干净后重新 apply 只补剩余）：\n  sillyspec worktree apply ${changeName} --skip-overlap\n` +
           (result.rescueCommands.commands.length > 0 || result.rescueCommands.warnings.length > 0
             ? `或手动 rescue（旁路 git apply，逐文件 cp 安全子集；cp 后需手动 sillyspec worktree cleanup ${changeName}）：\n` +
               result.rescueCommands.commands.map(c => `  ${c}`).join('\n') +
@@ -539,6 +634,7 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
             : '')
         );
         if (!checkOnly) return result; // checkOnly 收集不短路（一次报全）；真实 apply 短路
+        }
       } else {
         // 无关脏文件放行（只校验重叠文件）：--3way 若因 autocrlf 报 does not match index 会被
         // step7 catch 回滚（交集空前提下无损，见上注释），stash 后重试即可——不再硬挡 rescue 手动路径
@@ -559,6 +655,27 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
     // 如果脏文件和本次 apply 的文件有交集 → 报错
     const conflictDirty = mainDirtyFiles.filter(f => changedFiles.includes(f));
     if (conflictDirty.length > 0) {
+      // --skip-overlap 同款剔除（4.5 过滤后此处残余多为 staged 口径差集，防御性同处理）
+      if (skipOverlap && !checkOnly) {
+        const skipSet5a = new Set(conflictDirty);
+        for (const f of conflictDirty) {
+          if (!result.skippedOverlapFiles.includes(f)) result.skippedOverlapFiles.push(f);
+        }
+        changedFiles = changedFiles.filter(f => !skipSet5a.has(f));
+        result.changedFiles = changedFiles;
+        result.deletedFiles = deletedFiles.filter(f => !skipSet5a.has(f));
+        result.hashMismatchFiles = (result.hashMismatchFiles || []).filter(f => !skipSet5a.has(f));
+        if (changedFiles.length === 0) {
+          result.errors.push(
+            `--skip-overlap：变更文件全部与主仓未提交改动重叠，无可应用子集：\n  ${conflictDirty.join('\n  ')}\n` +
+            `请先提交/stash 主仓改动后重试。`
+          );
+          return result;
+        }
+        result.warnings = (result.warnings || []).concat([
+          `--skip-overlap（5a 口径）：再剔除 ${conflictDirty.length} 个重叠文件：${conflictDirty.join(', ')}`
+        ]);
+      } else {
       const rescueDirty5a = computeRescueDirtyFiles(projectRoot);
       result.rescueCommands = generateRescueCommands({
         changedFiles, dirtyFiles: rescueDirty5a, hashMismatchFiles: result.hashMismatchFiles,
@@ -566,6 +683,7 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
       });
       result.errors.push(
         `主工作区有以下未 commit 的变更，会影响 apply：\n  ${conflictDirty.join('\n  ')}\n请先 commit 或 stash 这些变更。` +
+        `或应用非重叠部分：sillyspec worktree apply ${changeName} --skip-overlap` +
         (result.rescueCommands.commands.length > 0 || result.rescueCommands.warnings.length > 0
           ? `或手动 rescue（旁路 git apply，逐文件 cp 安全子集；cp 后需手动 sillyspec worktree cleanup ${changeName}）：\n` +
             result.rescueCommands.commands.map(c => `  ${c}`).join('\n') +
@@ -574,6 +692,7 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
           : '')
       );
       if (!checkOnly) return result; // checkOnly 收集不短路（一次报全）；真实 apply 短路
+      }
     }
   }
 
@@ -713,11 +832,37 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
     } catch { /* pathspec 落盘失败不影响 apply 结果 */ }
 
     // --- 8. 成功后自动 cleanup（失败不影响整体结果） ---
+    // --skip-overlap 时先查 hasUnappliedChanges：跳过文件未落主仓 → 保留 worktree（不触发
+    // cleanup 的拦截横幅吓人，主动判断 + 温和提示）；全部已落地（无跳过残留）才照常清理。
+    // cleanup 返回值必须消费（坑 ghost-dir-junction-pierce，2026-08-23 实证：apply 后 partial
+    // 残留被静默丢弃，用户以为已干净、人工 rm -rf 时穿透 junction 删主仓 node_modules）。
+    const consumeCleanup = (cr) => {
+      if (cr && (cr.result === 'partial' || (Array.isArray(cr.residual) && cr.residual.length > 0))) {
+        result.warnings.push(
+          `⚠️ worktree 部分清理残留（${cr.result}）：${(cr.residual || []).join('; ') || 'worktree 目录'}` +
+          `——Windows 勿直接 rm -rf（会穿透 node_modules junction 删主仓依赖）：先 cmd /c rmdir "<worktree>\\node_modules" 解链再删目录，或跑 sillyspec worktree doctor --fix`
+        )
+      }
+      return cr
+    }
     try {
-      wm.cleanup(changeName, { force: true });
+      if (skipOverlap) {
+        const unapplied = wm.hasUnappliedChanges(changeName);
+        if (unapplied.hasChanges) {
+          const pend = unapplied.changedFiles || [];
+          result.warnings.push(
+            `worktree 已保留（--skip-overlap 有未应用文件）：${pend.length} 个文件仍在 worktree` +
+            `（${pend.slice(0, 5).join(', ')}${pend.length > 5 ? ' 等' : ''}）——主仓提交/stash 后重新 sillyspec worktree apply ${changeName} 只应用剩余文件，或确认放弃后 sillyspec worktree cleanup ${changeName} --force`
+          );
+        } else {
+          consumeCleanup(wm.cleanup(changeName, { force: true }));
+        }
+      } else {
+        consumeCleanup(wm.cleanup(changeName, { force: true }));
+      }
     } catch (cleanupErr) {
       result.warnings = result.warnings || [];
-      result.warnings.push(`cleanup 失败（不影响应用结果）: ${cleanupErr.message}`);
+      result.warnings.push(`cleanup 失败（不影响应用结果；Windows 手动清理先解 junction 再删，勿 rm -rf）: ${cleanupErr.message}`);
     }
 
   } catch (e) {
@@ -729,7 +874,8 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
         [`patch 生成超出进程缓冲区（ENOBUFS，超大 diff）——自动降级 git merge 路径应用`]
       );
       try {
-        return applyByMerge(result, changeName, projectRoot, wm);
+        // keepConflicts:false——自动降级路径无人善后冲突状态，维持 abort 回滚干净态
+        return applyByMerge(result, changeName, projectRoot, wm, { keepConflicts: false });
       } catch (mergeErr) {
         result.errors.push(`ENOBUFS 降级 merge 也失败: ${mergeErr.message}`);
         return result;
@@ -966,7 +1112,14 @@ function preAlignBaselineToMain({ meta, branch, projectRoot, result }) {
  * @param {object} wm - WorktreeManager 实例
  * @returns {object} result（merged=true 表示走了 merge 降级）
  */
-function applyByMerge(result, changeName, projectRoot, wm) {
+// opts.keepConflicts（坑 merge-conflict-abort-no-chance，2026-08-23 实证：--merge 遇冲突直接
+// abort 回滚，用户想手工解决只能自己重新 git merge——冲突现场与解决上下文全部丢失）：
+//   true（显式 --merge 路径）→ 冲突时保留 merge-in-progress 现场 + 完整解决指引（编辑冲突 →
+//     git add + git commit；或 git merge --abort 放弃）。worktree/分支/meta 本就保留。
+//   false（ENOBUFS 自动降级路径，默认）→ 维持 abort——自动降级无人善后冲突状态，回滚到
+//     干净态让用户显式重来更安全。
+export function applyByMerge(result, changeName, projectRoot, wm, opts = {}) {
+  const { keepConflicts = false } = opts;
   const meta = wm.getMeta(changeName);
   const changedFiles = result.changedFiles || [];
   // 用 meta.branch（native-worktree 模式分支名可能不是 sillyspec/<change>），不硬编码。
@@ -978,12 +1131,36 @@ function applyByMerge(result, changeName, projectRoot, wm) {
   try {
     git(projectRoot, ['merge', '--no-ff', branch], { timeout: 30000 });
   } catch (e) {
-    // merge 冲突：取冲突文件列表 + abort 回滚（不 cleanup，保留 worktree）
+    // merge 失败两形态须区分（原实现混为一谈：dirty 拒绝启动也被当「冲突」报）：
+    //   ① 未启动：主仓有会被合并覆盖的未提交改动，git 直接拒绝（无 MERGE_HEAD）——没有现场
+    //      可保留也无需 abort，指引 commit/stash 或 --skip-overlap
+    //   ② 真冲突：merge 已启动留 MERGE_HEAD + 冲突标记——keepConflicts 时保留现场供手工解决
     let conflictFiles = [];
     try {
       const cf = gitQuiet(projectRoot, ['diff', '--name-only', '--diff-filter=U']);
       conflictFiles = cf ? cf.split('\n').filter(Boolean) : [];
     } catch {}
+    const mergeInProgress = gitQuiet(projectRoot, ['rev-parse', '-q', '--verify', 'MERGE_HEAD']) !== null;
+    if (!mergeInProgress) {
+      result.errors.push(
+        `git merge ${branch} 未执行成功——主仓有会被合并覆盖的未提交改动，git 拒绝启动合并（无冲突现场）。\n` +
+        `git 输出: ${String(e.message || '').split('\n').slice(0, 3).join(' | ').slice(0, 300)}\n` +
+        `请先 commit/stash 主仓改动后重试，或用 --skip-overlap 应用非重叠子集。`
+      );
+      return result;
+    }
+    if (keepConflicts) {
+      // 保留冲突现场（显式 --merge）：主仓处于 merge-in-progress（MERGE_HEAD + unmerged index +
+      // 冲突标记），用户可直接手工解决——解决前 git 操作受限由指引明示，sillyspec 主仓命令
+      // （apply/cleanup 等）也会被 dirty/merge 状态挡住，属预期。
+      result.errors.push(
+        `git merge ${branch} 冲突，已在主仓保留冲突现场（未 abort）。冲突文件：\n` +
+        (conflictFiles.length ? `  ${conflictFiles.join('\n  ')}\n` : `  (未能获取冲突文件列表——git diff --name-only --diff-filter=U 查看)\n`) +
+        `手工解决：编辑上述冲突文件 → git add <file> → git commit 完成合并（worktree/分支已保留，解决后无需重跑 apply）。\n` +
+        `放弃合并：git merge --abort 回到合并前状态后重试。注意：解决前主仓处于 merge 中状态，其他 sillyspec 主仓命令会被阻挡。`
+      );
+      return result;
+    }
     try { gitQuiet(projectRoot, ['merge', '--abort']); } catch {}
     result.errors.push(
       `git merge ${branch} 冲突，请手动解决。冲突文件：\n` +

package/src/worktree-deps.js

@@ -129,9 +129,33 @@ function tryLink(mainNodeModules, linkPath) {
       const resolvedTarget = realpathSync(mainNodeModules);
       if (resolved === resolvedTarget) return { ok: true, method: process.platform === 'win32' ? 'junction' : 'symlink' };
     } catch {}
+    // 真实目录 ≠ 已有依赖（坑 provision-preexisting-dir-fake-linked，2026-08-23 实证：doctor --fix
+    // 报 re-provisioned 但链接没建——worktree node_modules 是 install 半途中断残留的真实目录时，
+    // realpath 不等 main → 被 preexisting 短路标 ok，根快路径据此写 depsStatus=linked，一个链接
+    // 都没建且后验证 existsSync 对空/残目录照样过）。真实目录 → ok:false + preexistingDir 标记，
+    // 交调用方决策：根快路径降级 tryInstall 真重建（宁可重装不说谎）；linkOneDir 视为本地安装
+    // 保留（installed 语义，合法状态）。指向别处的 link 仍是「他者安装」，尊重不 clobber。
+    try {
+      if (!lstatSync(linkPath).isSymbolicLink()) {
+        return { ok: false, preexistingDir: true, error: `node_modules 已存在且为真实目录（非链接，疑似 install 残留）: ${linkPath}` };
+      }
+    } catch {}
     // 指向别处 → 不 clobber，视为已有依赖（installed 语义）
     return { ok: true, method: 'install', preexisting: true };
   }
+  // broken junction 清理（existsSync 对目标丢失的 junction/symlink 返回 false，但目录项占位会使
+  // mklink/ln 撞名失败 → 根：落 install 慢路径；子模块：linkOneDir failed。此坑在 _doctorReprovision
+  // 的解链段同样存在——它也用 existsSync 前置判断，broken junction 永远解不掉）：lstat 是 link 而
+  // existsSync false → 删目录项后重建（rmdir 删 junction 不跟随 reparse，与 worktree.js 解链同款）。
+  try {
+    if (lstatSync(linkPath).isSymbolicLink()) {
+      if (process.platform === 'win32') {
+        execFileSync('cmd.exe', ['/c', 'rmdir', linkPath], { stdio: ['pipe', 'pipe', 'pipe'] });
+      } else {
+        unlinkSync(linkPath);
+      }
+    }
+  } catch { /* lstat 抛 = 目录项真不存在，直接建 */ }
   try {
     if (process.platform === 'win32') {
       // execFileSync 数组形式不经 shell：POSIX 双引号内 `/$() 会执行、cmd.exe 双引号内 %VAR% 仍展开，
@@ -292,6 +316,9 @@ function linkOneDir(wtDir, mainDir) {
   }
   const r = tryLink(mainNodeModules, join(wtDir, 'node_modules'));
   if (r.ok) return { status: 'linked', method: r.method };
+  // 真实目录 = 子模块本地安装过（合法状态，如 mismatch 后用户手动 pnpm install）：保留为
+  // installed 真话，不假 linked 也不误报 failed（tryLink 的 preexistingDir 细分见其注释）
+  if (r.preexistingDir) return { status: 'installed', reason: '子模块 node_modules 为真实目录（本地安装），保留' };
   return { status: 'failed', error: r.error };
 }
 
@@ -443,6 +470,17 @@ export function provisionDeps(worktreePath, mainCwd, opts = {}) {
       const fmsg = failedModules.map(m => `${m.path}: ${m.error}`).join('; ');
       result.depsError = result.depsError ? `${result.depsError}; ${fmsg}` : fmsg;
     }
+    // mismatch 可见性（坑 modules-mismatch-invisible，2026-08-23 实证：mismatch/skipped 只写
+    // depsModules 而 src 内零消费——doctor 报 re-provisioned 成功、子模块实际无链接且无任何
+    // 提示）。mismatch（worktree 与主仓 lockfile 不一致，link 不适用）摘要进 depsError：可见、
+    // 落 meta、doctor msg 带出（_doctorReprovision 不再抹）；但不降级 depsStatus——mismatch 是
+    // 配置分叉态不是供给失败，降级会经 deps gate 卡死 execute（正确动作是用户在 worktree 跑
+    // pnpm install 或对齐 lockfile， doctor --fix 的 force 重装路径也会覆盖此场景）。
+    const mismatchModules = moduleResults.filter(m => m.status === 'mismatch');
+    if (mismatchModules.length > 0) {
+      const mmsg = `子模块 lockfile 与主仓不一致（未链接，本地 install 或对齐 lockfile）: ${mismatchModules.map(m => m.path).join('、')}`;
+      result.depsError = result.depsError ? `${result.depsError}; ${mmsg}` : mmsg;
+    }
   }
 
   return result;
@@ -492,6 +530,25 @@ export function checkDepsFreshness(meta, wtPath, mainCwd) {
     };
   }
 
+  // 2b. 子模块 missing（坑 modules-submodule-missing-no-selfheal）：meta.depsModules 中 linked
+  // 状态的子模块逐一核验 wt/<mp>/node_modules 实存。provisionDeps 内的同款核验（坑
+  // modules-submodule-link-verify）只管供给时刻，此后 junction 被删（杀毒/手工误删/半途清理）
+  // 时本函数只查根（上方）→ 永远 fresh → doctor 不再报 → 漏链永不自愈。此处补 doctor 侧
+  // 闭环：缺失 → missing → doctor --fix 走 relinkFirst 重链（provisionDeps 非 force 路径
+  // 的 linkOneDir 对缺失目录直接重建 junction）。
+  if (Array.isArray(meta && meta.depsModules)) {
+    const missingMods = meta.depsModules.filter(m =>
+      m && m.status === 'linked' && typeof m.path === 'string'
+      && !existsSync(join(wtPath, m.path, 'node_modules')));
+    if (missingMods.length > 0) {
+      return {
+        status: 'missing',
+        detail: `${missingMods.length} 个 linked 子模块 node_modules 缺失: ${missingMods.map(m => m.path).join('、')}`,
+        wtHash, mainHash, metaLockHash,
+      };
+    }
+  }
+
   // 3. stale：worktree 自身 lockfile 与 meta 快照不一致（对齐 doctor 916-917 / ensure 404）
   if (metaLockHash && wtHash && wtHash !== metaLockHash) {
     return {