sillyspec 3.27.6 → 3.27.9

package/src/worktree-apply.js

@@ -16,6 +16,7 @@ import { existsSync, unlinkSync, writeFileSync, mkdtempSync, rmSync, readdirSync
 import { join, resolve } from 'path';
 import { tmpdir } from 'os';
 import { WorktreeManager } from './worktree.js';
+import { getCrossWorktreeMeta, cleanupCrossWorktrees } from './worktree-cross.js';
 import { parseFileChangeList, parseFileChangeListDetailed, pathMatches } from './change-list.js';
 import { parseAllowedPaths, parseRepo } from './stages/plan-postcheck.js';
 import { git, gitQuiet } from './git-helper.js';
@@ -23,6 +24,22 @@ import { resolveLatestExecuteRunId, resolveLatestExecuteRunIdWithTasks, readRevi
 
 const CHANGES_REL = '.sillyspec/changes';
 
+/**
+ * cleanup 返回值必须消费（坑 ghost-dir-junction-pierce，2026-08-23 实证：apply 后 partial
+ * 残留被静默丢弃，用户以为已干净、人工 rm -rf 时穿透 junction 删主仓 node_modules）。
+ * 模块级共享：applyWorktree 无变更早退 / skip-overlap / applyByMerge 成功路径三处统一走此消费。
+ */
+function consumeCleanupResult(cr, result) {
+  if (cr && (cr.result === 'partial' || (Array.isArray(cr.residual) && cr.residual.length > 0))) {
+    result.warnings = result.warnings || [];
+    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;
+}
+
 /**
  * 过滤掉 worktree 基础设施文件（非交付物），让 apply 只关心真正的变更产出：
  *   - meta.json：worktree 元数据，baseline commit 中被跟踪、working-tree 被 CLI 改写
@@ -424,6 +441,182 @@ export async function withMainRepoLock(projectRoot, changeName, purpose, fn, opt
   }
 }
 
+/**
+ * 跨仓 worktree 真实 apply（坑 cross-repo-no-worktree-isolation，2026-08-27）。
+ *
+ * 对有 worktree meta 的跨仓仓（worktree-cross.js 创建）执行与主仓 A5 同构的 patch 回落：
+ *   deliverables（diff baselineCommit||baseHash + untracked，filterDeliverableFiles 排除基础设施）
+ *   → 清单校验（resolveApplyAllowSet 按 repo 切片 ∪ review 声明切片）
+ *   → 跨仓主工作副本 dirty 重叠拦截
+ *   → patch（tracked diff + untracked add/diff --cached/reset，Buffer 防二进制损坏）
+ *   → git apply --3way 回跨仓主工作副本；成功后 cleanup 该跨仓 worktree（分支保留作锚）。
+ *
+ * 与主仓 apply 的顺序契约：本函数在主仓 patch 动作**之前**调用——任一跨仓失败即整体报错返回，
+ * 主仓工作区不动（不留半套状态）。legacy 直写模式的跨仓仓无 meta，不走本函数（原 no-op 校验）。
+ *
+ * @param {string} changeName
+ * @param {string} projectRoot 主仓根
+ * @param {object} ctx MultiRepoContext
+ * @param {{ checkOnly?: boolean }} opts
+ * @returns {{ repos: string[], applied: Array<{repoKey, changedFiles}>, errors: string[], warnings: string[], crossCleanups: string[] }}
+ */
+function applyCrossRepoWorktrees(changeName, projectRoot, ctx, { checkOnly = false } = {}) {
+  const specBase = (ctx.platformOpts && ctx.platformOpts.specRoot) || join(projectRoot, '.sillyspec');
+  const out = { repos: [], applied: [], errors: [], warnings: [], crossCleanups: [] };
+  for (const [repoKey, entry] of ctx.repos) {
+    if (entry.isMain) continue;
+    const cm = getCrossWorktreeMeta(specBase, changeName, repoKey);
+    if (!cm || !cm.isCross || !cm.worktreePath || !existsSync(cm.worktreePath)) continue;
+    out.repos.push(repoKey);
+    const crossRoot = cm.crossRepoRoot || entry.projectRoot;
+    const deliverableBase = cm.baselineCommit || cm.baseHash;
+
+    // 交付集合（与主仓 step2 同口径：--name-status 捕 rename/delete + untracked，过滤基础设施文件）
+    let changedFiles = [];
+    const deletedFiles = [];
+    try {
+      const statusRaw = git(cm.worktreePath, ['diff', '--name-status', deliverableBase]);
+      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]);
+          if (parts[0].startsWith('D')) deletedFiles.push(parts[parts.length - 1]);
+        }
+      }
+      const untrackedRaw = gitQuiet(cm.worktreePath, ['ls-files', '--others', '--exclude-standard']) || '';
+      changedFiles = filterDeliverableFiles([...new Set([...statusFiles, ...untrackedRaw.split('\n').filter(Boolean)])]);
+    } catch (e) {
+      out.errors.push(`跨仓 ${repoKey}：获取变更文件列表失败（${cm.worktreePath}）: ${e.message}`);
+      continue;
+    }
+
+    if (changedFiles.length === 0) {
+      if (!checkOnly) {
+        const cr = cleanupCrossWorktrees({ cwd: crossRoot, changeName, specBase, force: true });
+        for (const r of cr.results) {
+          if (r.result === 'cleaned') out.crossCleanups.push(`${repoKey}（无变更，worktree 已清理）`);
+          else out.warnings.push(`跨仓 ${repoKey} 无变更但清理 partial：${(r.details || []).join('; ')}`);
+        }
+      }
+      out.applied.push({ repoKey, changedFiles: [] });
+      continue;
+    }
+
+    // 清单校验（per-repo 切片 + review 声明切片并入，与主仓 Gate1/3b 同语义）
+    const allowMap = resolveApplyAllowSet(projectRoot, changeName);
+    let allowSet = allowMap.get(repoKey) || new Set();
+    const reviewDeclared = collectReviewDeclaredFiles(projectRoot, changeName).get(repoKey);
+    if (reviewDeclared) {
+      const merged = new Set([...allowSet]);
+      for (const f of reviewDeclared) {
+        if (![...merged].some(ap => pathMatches(f, ap))) merged.add(f);
+      }
+      allowSet = merged;
+    }
+    if (allowSet.size > 0) {
+      const violations = classifyAllowListViolations(changedFiles, allowSet);
+      if (violations.length > 0) {
+        out.errors.push(
+          `跨仓 ${repoKey}：文件清单校验失败——以下变更文件不在 design.md 清单、也不在该仓 task review.json changedFiles 声明中：\n  ${violations.join('\n  ')}`
+        );
+        if (!checkOnly) continue;
+      }
+    }
+
+    if (checkOnly) {
+      out.applied.push({ repoKey, changedFiles });
+      continue;
+    }
+
+    // 跨仓主工作副本 dirty 重叠拦截（与主仓 step4.5 同语义：重叠 = git apply 无法安全应用）
+    try {
+      const dirtyFiles = [...new Set(
+        ((gitQuiet(crossRoot, ['diff', '--name-only', 'HEAD']) || '').split('\n').filter(Boolean))
+          .concat((gitQuiet(crossRoot, ['ls-files', '--others', '--exclude-standard']) || '').split('\n').filter(Boolean))
+      )].filter(f => !f.startsWith('.sillyspec/') && f !== 'meta.json');
+      const overlap = dirtyFiles.filter(f => changedFiles.includes(f));
+      if (overlap.length > 0) {
+        out.errors.push(
+          `跨仓 ${repoKey}（${crossRoot}）主工作副本以下未提交文件与本次 apply 重叠，无法安全应用：\n  ${overlap.join('\n  ')}\n` +
+          `请先在跨仓仓提交或 stash 这些改动后重试 apply。`
+        );
+        continue;
+      }
+    } catch (e) {
+      out.errors.push(`跨仓 ${repoKey}：dirty 重叠检测失败（${crossRoot}）: ${e.message}`);
+      continue;
+    }
+
+    // patch 生成 + apply --3way（tracked/untracked 分流与 Buffer 聚合，与主仓 step7 同款）
+    const patchFiles = allowSet.size > 0
+      ? resolvePatchFiles(changedFiles, allowSet, true)
+      : changedFiles;
+    const tmpDir = mkdtempSync(join(tmpdir(), 'sillyspec-cross-'));
+    const patchPath = join(tmpDir, 'apply.patch');
+    try {
+      const inTree = new Set(
+        (gitQuiet(cm.worktreePath, ['ls-tree', '-r', '--name-only', deliverableBase]) || '').split('\n').filter(Boolean)
+      );
+      const inIndexRaw = patchFiles.length > 0
+        ? (gitQuiet(cm.worktreePath, ['ls-files', '--', ...patchFiles]) || '')
+        : '';
+      const inIndex = new Set(inIndexRaw.split('\n').filter(Boolean));
+      const trackedFiles = patchFiles.filter(f => inTree.has(f) || inIndex.has(f));
+      const untrackedPatchFiles = patchFiles.filter(f => !trackedFiles.includes(f));
+      const patchParts = [];
+      if (trackedFiles.length > 0) {
+        patchParts.push(git(cm.worktreePath, ['diff', '--binary', deliverableBase, '--', ...trackedFiles], { encoding: 'buffer', timeout: 60000 }));
+      }
+      if (untrackedPatchFiles.length > 0) {
+        git(cm.worktreePath, ['add', '--', ...untrackedPatchFiles]);
+        try {
+          patchParts.push(git(cm.worktreePath, ['diff', '--binary', '--cached', '--', ...untrackedPatchFiles], { encoding: 'buffer', timeout: 60000 }));
+        } finally {
+          gitQuiet(cm.worktreePath, ['reset', 'HEAD', '--', ...untrackedPatchFiles]);
+        }
+      }
+      const patchContent = Buffer.concat(patchParts);
+      if (patchContent.length === 0) {
+        out.applied.push({ repoKey, changedFiles: [] });
+        continue;
+      }
+      writeFileSync(patchPath, patchContent);
+      try {
+        git(crossRoot, ['apply', '--3way', patchPath], { timeout: 30000 });
+      } catch (e) {
+        // 冲突回滚：tracked 文件还原 HEAD 版，--3way 新建的部分文件删除（与主仓 rollbackApply 同语义）
+        const rawStderr = e.message || '';
+        for (const f of patchFiles) {
+          try {
+            if (gitQuiet(crossRoot, ['cat-file', '-e', `HEAD:${f}`]) !== null) {
+              gitQuiet(crossRoot, ['checkout', 'HEAD', '--', f]);
+            } else {
+              try { rmSync(join(crossRoot, f), { force: true }) } catch { /* 新文件删除失败留残，rescue 提示 */ }
+            }
+          } catch { /* 回滚尽力而为 */ }
+        }
+        out.errors.push(
+          `跨仓 ${repoKey}：apply --3way 失败（已回滚跨仓主工作副本到 apply 前状态）：${rawStderr}\n` +
+          `可选：进 ${crossRoot} 手工合并 worktree 分支 ${cm.branch}（git merge ${cm.branch}），完成后手动清理跨仓 worktree。`
+        );
+        continue;
+      }
+      out.applied.push({ repoKey, changedFiles: patchFiles });
+      // 成功 → 清理该跨仓 worktree（分支保留作 review 锚点）
+      const cr = cleanupCrossWorktrees({ cwd: crossRoot, changeName, specBase, force: true });
+      for (const r of cr.results) {
+        if (r.result === 'cleaned') out.crossCleanups.push(repoKey);
+        else out.warnings.push(`跨仓 ${repoKey} apply 成功但清理 partial：${(r.details || []).join('; ')}${(r.residual || []).length ? '；残留: ' + r.residual.join('; ') : ''}`);
+      }
+    } finally {
+      try { rmSync(tmpDir, { recursive: true, force: true }) } catch { /* 临时目录清理尽力而为 */ }
+    }
+  }
+  return out;
+}
+
 export function applyWorktree(changeName, { cwd, checkOnly = false, merge = false, base = 'merge-base', ctx = null, skipOverlap = false, stashDirty = false } = {}) {
   const projectRoot = cwd || process.cwd();
   const wm = new WorktreeManager({ cwd: projectRoot });
@@ -442,11 +635,26 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
     skippedOverlapFiles: [],
   };
 
-  // --- 0. 跨仓 task no-op 校验（task-05 / D-009） ---
-  // 跨仓 task 的 commit 已落跨仓仓主干，apply = no-op（无 patch）。仅校验 review.head 是跨仓仓真实
-  // commit + 不 cleanup（wm.cleanup 只作用主仓 worktree）。校验失败 → 推 errors 阻断 apply（R-05）。
-  // 单仓 ctx 缺省 / 无跨仓 entry → validateCrossRepoNoOp 直接返回空（零回归）。
+  // --- 0. 跨仓处理（task-05 / D-009 + 坑 cross-repo-no-worktree-isolation） ---
+  // 0a. worktree 模式的跨仓仓：真实 apply（patch 回跨仓主工作副本 + 成功后 cleanup worktree）。
+  //     在主仓任何动作之前跑——任一跨仓失败即整体返回，主仓工作区不动（不留半套状态）。
+  // 0b. legacy 直写模式的跨仓仓：no-op 校验（review.head 是跨仓真实 commit + 不 cleanup）。
+  // 单仓 ctx 缺省 / 无跨仓 entry → 两步都空转（零回归）。
   if (ctx) {
+    const crossApplied = applyCrossRepoWorktrees(changeName, projectRoot, ctx, { checkOnly });
+    if (crossApplied.repos.length > 0) {
+      result.crossRepoApplied = crossApplied.applied;
+      for (const w of crossApplied.warnings) result.warnings = (result.warnings || []).concat([w]);
+      if (crossApplied.crossCleanups.length > 0) {
+        result.warnings = (result.warnings || []).concat([
+          `跨仓 worktree 已 apply 并清理：${crossApplied.crossCleanups.join(', ')}（分支保留作 review 锚点）`
+        ]);
+      }
+      if (crossApplied.errors.length > 0) {
+        result.errors.push(...crossApplied.errors);
+        return result; // 跨仓未落地 = 该仓 task 实际未完成，主仓 apply 不可继续
+      }
+    }
     const cross = validateCrossRepoNoOp(ctx, projectRoot, changeName);
     for (const e of cross.errors) result.errors.push(e);
     if (cross.warnings.length > 0) result.warnings = (result.warnings || []).concat(cross.warnings);
@@ -496,6 +704,10 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
   // 同时检测 untracked 新文件（git diff 不包含 untracked）
   let changedFiles;
   const deletedFiles = [];
+  // merge 后应「不存在于 main HEAD」的文件（D 删除 + R/C rename/copy 源路径）：
+  // applyByMerge 落地校验按此分流——原实现一律要求 cat-file 存在，含删除文件的变更
+  // merge 成功也恒报「未落地」失败、worktree 永不清理（坑 apply-merge-deleted-misjudged）
+  const absentAfterMerge = [];
   try {
     // 用 --name-status 捕获 rename/delete（--name-only 会丢失 rename 源文件）
     // 交付集合判定：用 deliverableBase（baselineCommit||baseHash），保「只合子代理改动」语义
@@ -509,8 +721,11 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
         if (parts.length >= 3) statusFiles.add(parts[parts.length - 2]);
         // 删除文件（status D / D100）→ 收集到 deletedFiles（rescue DELETE 分类用，design §逐文件分类）
         if (parts[0].startsWith('D')) deletedFiles.push(parts[parts.length - 1]);
+        // rename/copy 源路径（R100/C99 old new 三段式）→ 同删除语义：merge 后 HEAD 中不应存在
+        if (parts.length >= 3 && !parts[0].startsWith('D')) absentAfterMerge.push(parts[parts.length - 2]);
       }
     }
+    for (const f of deletedFiles) absentAfterMerge.push(f);
 
     // untracked 新文件（deliverableBase 中不存在的文件）
     const untrackedRaw = gitQuiet(worktreePath, ['ls-files', '--others', '--exclude-standard']);
@@ -527,11 +742,12 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
 
   result.changedFiles = changedFiles;
   result.deletedFiles = deletedFiles;
+  result.absentAfterMerge = absentAfterMerge;
 
   if (changedFiles.length === 0) {
     // 没有变更
     if (!checkOnly) {
-      wm.cleanup(changeName, { force: true });
+      consumeCleanupResult(wm.cleanup(changeName, { force: true }), result);
     }
     result.ok = true;
     return result;
@@ -936,15 +1152,9 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
       // 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
-      }
+      // cleanup 返回值必须消费（坑 ghost-dir-junction-pierce）——实现提升为模块级 consumeCleanupResult，
+      // 与无变更早退 / applyByMerge 成功路径三处共用
+      const consumeCleanup = (cr) => consumeCleanupResult(cr, result)
       try {
         if (skipOverlap) {
           const unapplied = wm.hasUnappliedChanges(changeName);
@@ -1329,13 +1539,19 @@ export function applyByMerge(result, changeName, projectRoot, wm, opts = {}) {
 
   // 落地校验：merge 报成功（exit 0）不代表交付物真进 main——
   // 分支可能只含 baseline checkpoint（子代理改动未 commit），merge 产生空内容合并，文件零落地。
-  // 逐个确认 changedFiles 在 main HEAD 存在。任一缺失 → 不 cleanup（fail-open：保留 worktree 唯一副本）。
+  // 落地语义按文件类型分流：普通交付文件应存在于 main HEAD；删除/rename 源文件（absentAfterMerge）
+  // 应「不存在」——原实现一律要求存在，含删除文件的变更 merge 成功也恒报失败（坑 apply-merge-deleted-misjudged）。
+  // 任一未按预期落地 → 不 cleanup（fail-open：保留 worktree 唯一副本）。
   result.merged = true;
-  const notLanded = changedFiles.filter(f => gitQuiet(projectRoot, ['cat-file', '-e', `HEAD:${f}`]) === null);
+  const absentExpected = new Set(result.absentAfterMerge || []);
+  const notLanded = changedFiles.filter(f => {
+    const inHead = gitQuiet(projectRoot, ['cat-file', '-e', `HEAD:${f}`]) !== null;
+    return absentExpected.has(f) ? inHead : !inHead;
+  });
   if (notLanded.length > 0) {
     result.ok = false;
     result.errors.push(
-      `git merge ${branch} 报成功，但 ${notLanded.length}/${changedFiles.length} 个交付文件未出现在 main HEAD` +
+      `git merge ${branch} 报成功，但 ${notLanded.length}/${changedFiles.length} 个交付文件未按预期落地 main HEAD` +
       `（分支可能只含 baseline checkpoint，子代理改动未 commit）。worktree 已保留（未 cleanup），` +
       `请用 git cherry-pick 或手动 cp 落地：\n  ${notLanded.join('\n  ')}`
     );
@@ -1345,7 +1561,7 @@ export function applyByMerge(result, changeName, projectRoot, wm, opts = {}) {
   result.ok = true;
   try { result.mergeSummary = git(projectRoot, ['log', '--oneline', '-1']); } catch {}
   try {
-    wm.cleanup(changeName, { force: true });
+    consumeCleanupResult(wm.cleanup(changeName, { force: true }), result);
   } catch (cleanupErr) {
     result.warnings = result.warnings || [];
     result.warnings.push(`cleanup 失败（不影响 merge 结果）: ${cleanupErr.message}`);

package/src/worktree-cross.js

@@ -0,0 +1,294 @@
+/**
+ * worktree-cross.js — 跨仓仓 worktree 隔离（坑 cross-repo-no-worktree-isolation，2026-08-27 用户实证）。
+ *
+ * 背景：跨仓 task 的原设计（multi-repo W1 D-005/D-006/D-009）是子代理直写跨仓仓主工作副本、
+ * commit 直落该仓主干，apply 对跨仓 no-op。实战暴露三类事故面：
+ *   1. 并行混流：跨仓主工作副本常有用户/其他变更的在途改动，子代理产物与之混在同一工作区，
+ *      无法区分归属、无法整体回滚（实证：sub-grid-security 主工作副本 task-05 产物与
+ *      .gitignore/.webpackrc.js/yarn.lock 并行改动混流，无法核对）；
+ *   2. 无 base 锚：跨仓仓无 meta/baseHash，base 只能靠 task 卡 base_commit 锡点；
+ *   3. 误伤面大：子代理在主工作副本可误改/误删用户未提交文件，无护栏。
+ *
+ * 本模块把跨仓仓纳入与主仓同构的 worktree 隔离（D-009 就地翻新，向后兼容）：
+ *   - worktree 落位 <主仓 specBase>/.runtime/worktrees/<change>--<repoKey>：主仓侧该目录已被
+ *     .gitignore 覆盖（主仓 create 已强制检查），不要求跨仓仓自配 .gitignore；git worktree
+ *     的注册信息在跨仓 .git/worktrees/，目录本身可在仓外任意路径；
+ *   - meta.json 与主仓同 schema + repoKey/crossRepoRoot/isCross 标识（唯一写入方 = 本模块，
+ *     multi-repo-context.js 只读且路径公式与此处 crossWorktreePath 保持同步）；
+ *   - base 锚 meta.baseHash（跨仓仓 HEAD 快照）；dirty baseline overlay 沿用主仓同款
+ *     （跨仓主工作副本的在途改动进 baseline，不算交付 diff，apply 不覆盖它们）；
+ *   - deps 供给 provisionDeps(worktree, 跨仓根, {specBase:null})——sniff worktree 自身项目
+ *     类型（package.json→nodejs 链主工作副本 node_modules；不沿用主仓 local.yaml 的
+ *     project.type，主仓与跨仓类型常不同，如实测 maven 主仓 + nodejs 前端仓）；
+ *   - cleanup：解链 node_modules junction → git worktree remove --force → 保留分支
+ *     sillyspec/<change> 作 review 锚点（对齐主仓 cleanup 的分支保护哲学）。
+ *
+ * 兼容：无跨仓 worktree meta 的旧变更（legacy 直写主干模式）各链路继续走原路径，零回归。
+ */
+
+import { existsSync, readFileSync, readdirSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { git, gitQuiet } from './git-helper.js';
+import { writeAtomicSync } from './fs-atomic.js';
+import { WorktreeManager, unlinkNodeModulesLinks, safeRemoveWorktreeDir } from './worktree.js';
+import { provisionDeps } from './worktree-deps.js';
+import { aggregateDeclaredRepos } from './run/shared.js';
+import { parseRepoRegistry } from './stages/plan-postcheck.js';
+
+const META_FILE = 'meta.json';
+const BRANCH_PREFIX = 'sillyspec/';
+
+/**
+ * 跨仓 worktree 路径（唯一路径公式；multi-repo-context.js 的 meta 只读逻辑与此同步）。
+ * @param {string} specBase 主仓 spec 根（<主仓>/.sillyspec）
+ * @param {string} changeName 变更名
+ * @param {string} repoKey 跨仓 repo 键（local.yaml repos: 段的 key）
+ */
+export function crossWorktreePath(specBase, changeName, repoKey) {
+  return join(specBase, '.runtime', 'worktrees', `${changeName}--${repoKey}`);
+}
+
+/**
+ * 读跨仓 worktree meta（不存在/损坏返 null = legacy 直写模式）。
+ * @returns {object|null}
+ */
+export function getCrossWorktreeMeta(specBase, changeName, repoKey) {
+  const metaPath = join(crossWorktreePath(specBase, changeName, repoKey), META_FILE);
+  if (!existsSync(metaPath)) return null;
+  try {
+    return JSON.parse(readFileSync(metaPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 列出某变更已建的全部跨仓 worktree meta（扫描 worktrees 目录下 `<change>--*` 且 isCross 的 meta）。
+ * @returns {Array<{repoKey: string, meta: object}>}
+ */
+export function listCrossWorktreeMetas(specBase, changeName) {
+  const base = join(specBase, '.runtime', 'worktrees');
+  if (!existsSync(base)) return [];
+  const out = [];
+  for (const name of readdirSync(base)) {
+    if (!name.startsWith(`${changeName}--`)) continue;
+    const metaPath = join(base, name, META_FILE);
+    if (!existsSync(metaPath)) continue;
+    try {
+      const meta = JSON.parse(readFileSync(metaPath, 'utf8'));
+      if (meta && meta.isCross && meta.repoKey) out.push({ repoKey: meta.repoKey, meta });
+    } catch { /* 损坏 meta 跳过（cleanup 阶段仍按目录处理） */ }
+  }
+  return out;
+}
+
+/**
+ * 聚合声明跨仓 key（plan.md 内联卡片 + tasks/ 独立卡片双源，与 shared.js getOrCreateMultiRepoContext 同口径）。
+ * @param {string} specBase
+ * @param {string} changeName
+ * @returns {string[]} 除 'main' 外的跨仓 key（未注册/配置错由 MultiRepoContext fail-closed，此处只聚合）
+ */
+function aggregateCrossRepoKeys(specBase, changeName) {
+  const planFile = join(specBase, 'changes', changeName, 'plan.md');
+  let planContent = '';
+  if (existsSync(planFile)) {
+    try { planContent = readFileSync(planFile, 'utf8') } catch { planContent = '' }
+  }
+  // tasks/ 独立卡片兜底（与 run/shared.js collectTaskCardReposFallback 同口径，该函数未导出）
+  const tasksDir = join(specBase, 'changes', changeName, 'tasks');
+  if (existsSync(tasksDir)) {
+    for (const f of readdirSync(tasksDir)) {
+      if (!/^task-\d+\.md$/i.test(f)) continue;
+      try { planContent += '\n' + readFileSync(join(tasksDir, f), 'utf8') + '\n' } catch { /* 兜底源不阻断 */ }
+    }
+  }
+  return aggregateDeclaredRepos(planContent).filter(k => k !== 'main');
+}
+
+/**
+ * 读主仓 local.yaml 的 repos: 段（路径口径与 run/shared.js readLocalYamlRaw 一致：cwd/.sillyspec/local.yaml）。
+ * @returns {Map<string,string>}
+ */
+function readRepoRegistry(cwd) {
+  const p = join(cwd, '.sillyspec', 'local.yaml');
+  let text = '';
+  if (existsSync(p)) {
+    try { text = readFileSync(p, 'utf8') } catch { text = '' }
+  }
+  return parseRepoRegistry(text);
+}
+
+/**
+ * execute 启动时为每个声明的跨仓仓建 worktree（幂等：meta 在即复用）。
+ *
+ * 失败语义 fail-closed（对齐主仓 create：隔离建不起来就不该开工）：任何仓创建失败 → 抛错，
+ * 由调用方（run/stage.js execute 启动）exit(1) 并给修复指引。已建成功的仓保留（重跑幂等复用）。
+ *
+ * @param {{ cwd: string, changeName: string, specBase?: string }} opts
+ * @returns {{ created: Array<{repoKey,worktreePath}>, reused: Array<{repoKey,worktreePath}>, skippedLegacy: string[] }}
+ * @throws {Error} 跨仓仓未注册 / git 不可达 / worktree add 失败 / 分支冲突
+ */
+export function ensureCrossWorktrees({ cwd, changeName, specBase }) {
+  const base = specBase || join(cwd, '.sillyspec');
+  const keys = aggregateCrossRepoKeys(base, changeName);
+  const registry = readRepoRegistry(cwd);
+  const created = [];
+  const reused = [];
+  const skippedLegacy = [];
+
+  for (const key of keys) {
+    const repoRoot = registry.get(key);
+    if (!repoRoot) {
+      // 与 MultiRepoContext 约束②同语义：声明的 repo 必须已注册，配置错不降级
+      throw new Error(
+        `跨仓 repo "${key}" 未在 local.yaml repos: 段注册。` +
+        `一键注册：sillyspec local register-repo ${key} <${key} 仓根路径>（勿手编 YAML），补注册后重跑 execute。`
+      );
+    }
+    const existing = getCrossWorktreeMeta(base, changeName, key);
+    if (existing && existing.worktreePath && existsSync(existing.worktreePath)) {
+      reused.push({ repoKey: key, worktreePath: existing.worktreePath });
+      continue;
+    }
+    // meta 在但目录没了（外部误删）：走重建（下方 git worktree add 会因注册残留失败，
+    // 先 prune 掉悬空注册再建——目录不在则 prune 无损）
+    if (existing) {
+      try { gitQuiet(repoRoot, ['worktree', 'prune'], { timeout: 30000 }) } catch {}
+    }
+
+    const worktreePath = crossWorktreePath(base, changeName, key);
+    const branch = BRANCH_PREFIX + changeName;
+
+    // base 快照：跨仓仓当前 HEAD（与主仓 create 的默认 base 语义一致）
+    let baseHash;
+    try {
+      baseHash = git(repoRoot, ['rev-parse', 'HEAD']);
+    } catch (e) {
+      throw new Error(`跨仓 repo "${key}"（${repoRoot}）git 不可达（rev-parse HEAD 失败：${e.message}）。请检查 local.yaml repos: 段路径。`);
+    }
+    const branchExists = !!gitQuiet(repoRoot, ['rev-parse', '--verify', `refs/heads/${branch}`]);
+    if (branchExists) {
+      throw new Error(
+        `跨仓仓 ${key} 已有分支 ${branch}（疑似上次 execute 残留）。三选一：\n` +
+        `  ① 确认残留作废：git -C ${repoRoot} branch -D ${branch} 后重跑；\n` +
+        `  ② 分支内容已 apply 落地或不再需要：sillyspec worktree cleanup ${changeName} --force（跨仓 worktree 一并清理后重跑）；\n` +
+        `  ③ 换变更名重跑。`
+      );
+    }
+    mkdirSync(join(base, '.runtime', 'worktrees'), { recursive: true });
+    try {
+      git(repoRoot, ['worktree', 'add', worktreePath, '-b', branch, baseHash], { timeout: 120000 });
+    } catch (e) {
+      throw new Error(`跨仓仓 ${key} worktree 创建失败（${worktreePath}）：${e.stderr || e.message}`);
+    }
+
+    const meta = {
+      name_zh: 'worktree 元数据',
+      changeName,
+      repoKey: key,
+      crossRepoRoot: repoRoot,
+      isCross: true,
+      branch,
+      baseBranch: gitQuiet(repoRoot, ['symbolic-ref', '--short', 'HEAD']) || 'HEAD',
+      baseHash,
+      actualBaseHash: gitQuiet(worktreePath, ['rev-parse', 'HEAD']) || baseHash,
+      createdAt: new Date().toISOString(),
+      worktreePath,
+      mode: 'worktree',
+    };
+    writeAtomicSync(join(worktreePath, META_FILE), JSON.stringify(meta, null, 2) + '\n');
+
+    // dirty baseline overlay：跨仓主工作副本在途改动 → worktree baseline（借主仓同款实现，
+    // 只用其参数化逻辑，不用实例路径状态）
+    try {
+      const wmHelper = new WorktreeManager({ cwd: repoRoot });
+      const baselineResult = wmHelper._overlayBaseline(repoRoot, worktreePath);
+      meta.baselineFiles = baselineResult.files;
+      meta.baselineHash = baselineResult.baselineHash;
+      if (baselineResult.files.length > 0) {
+        meta.baselineCommit = wmHelper._createBaselineCheckpoint(worktreePath, `${changeName}--${key}`, baselineResult.files);
+      }
+      if (baselineResult.errors && baselineResult.errors.length > 0) {
+        console.warn(`⚠️ 跨仓 ${key} baseline overlay 部分失败（${baselineResult.errors.join('; ')}）——在途改动未全量进 baseline，apply 前请人工核对跨仓主工作副本`);
+      }
+      writeAtomicSync(join(worktreePath, META_FILE), JSON.stringify(meta, null, 2) + '\n');
+    } catch (e) {
+      console.warn(`⚠️ 跨仓 ${key} baseline overlay 失败（${e.message}）——跨仓主工作副本如有在途改动，worktree 不含它们`);
+    }
+
+    // deps 供给：specBase 传 null —— sniff worktree 自身（主仓 local.yaml 的 project.type/install
+    // 描述的是主仓，跨仓仓类型常不同，如实测 maven 主仓 + nodejs 前端仓，沿用会把 mvn 命令
+    // 打到前端仓上）。失败不阻断（与主仓 create 同语义，doctor --fix 可修）
+    try {
+      const deps = provisionDeps(worktreePath, repoRoot, { specBase: null }) || {};
+      Object.assign(meta, {
+        depsStatus: deps.depsStatus,
+        depsMethod: deps.depsMethod || null,
+        depsSource: deps.depsSource || null,
+        depsLockHash: deps.depsLockHash || null,
+        depsCheckedAt: deps.depsCheckedAt || null,
+        ...(deps.depsError ? { depsError: deps.depsError } : {}),
+      });
+      writeAtomicSync(join(worktreePath, META_FILE), JSON.stringify(meta, null, 2) + '\n');
+    } catch (e) {
+      meta.depsStatus = 'failed';
+      meta.depsError = `provisionDeps crashed: ${e.message}`;
+      writeAtomicSync(join(worktreePath, META_FILE), JSON.stringify(meta, null, 2) + '\n');
+    }
+
+    created.push({ repoKey: key, worktreePath });
+  }
+  return { created, reused, skippedLegacy };
+}
+
+/**
+ * 清理某变更的全部跨仓 worktree（幂等）。
+ *
+ * 顺序对齐主仓 cleanup 的 Windows 防护：先解 node_modules junction（裸删会穿透删跨仓主工作
+ * 副本的 node_modules），再 git worktree remove --force，最后**保留分支** sillyspec/<change>
+ * 作 review 锚点（分支删除在主仓侧有 review 锚点 + 双保护，跨仓侧 v1 保守不删，残 branch
+ * 可人工清理）。目录残留（remove 失败）走 safeRemoveWorktreeDir 兜底 + residual 上报。
+ *
+ * @param {{ cwd: string, changeName: string, specBase?: string, force?: boolean }} opts
+ * @returns {{ results: Array<{repoKey, result: 'cleaned'|'skipped'|'partial', details: string[], residual: string[]}> }}
+ */
+export function cleanupCrossWorktrees({ cwd, changeName, specBase, force = false }) {
+  const base = specBase || join(cwd, '.sillyspec');
+  const results = [];
+  for (const { repoKey, meta } of listCrossWorktreeMetas(base, changeName)) {
+    const details = [];
+    const residual = [];
+    const repoRoot = meta.crossRepoRoot;
+    const wtPath = meta.worktreePath || crossWorktreePath(base, changeName, repoKey);
+    if (!existsSync(wtPath)) {
+      try { if (repoRoot) gitQuiet(repoRoot, ['worktree', 'prune'], { timeout: 30000 }) } catch {}
+      results.push({ repoKey, result: 'skipped', details: ['目录不存在（已清理）'], residual });
+      continue;
+    }
+    if (!force) {
+      // fail-closed：worktree 内还有未落地交付（相对 baseHash 有 diff）时拒绝清理（对齐主仓
+      // hasUnappliedChanges 哲学；跨仓侧以「分支上有交付 diff 且未 apply」近似）
+      try {
+        const diff = gitQuiet(wtPath, ['diff', '--name-only', meta.baseHash]) || '';
+        const untracked = gitQuiet(wtPath, ['ls-files', '--others', '--exclude-standard']) || '';
+        if (diff.trim() || untracked.trim()) {
+          results.push({ repoKey, result: 'partial', details: [`blocked: 跨仓 worktree 有未 apply 的交付改动（git diff ${String(meta.baseHash).slice(0, 8)} 非空）——先 apply 或显式 --force`], residual: [wtPath] });
+          continue;
+        }
+      } catch (e) {
+        details.push(`未落地检测失败（${e.message}），按 force 处理`);
+      }
+    }
+    try { unlinkNodeModulesLinks(wtPath, meta, details) } catch (e) { details.push(`junction 解链失败: ${e.message}`) }
+    try {
+      git(repoRoot, ['worktree', 'remove', '--force', wtPath], { timeout: 60000 });
+    } catch {
+      // remove 失败（脏文件/锁）：解链后安全删目录 + prune 注册
+      try { safeRemoveWorktreeDir(wtPath, meta) } catch (e) { residual.push(`目录残留 ${wtPath}: ${e.message}`) }
+      try { gitQuiet(repoRoot, ['worktree', 'prune'], { timeout: 30000 }) } catch { residual.push(`git worktree prune 失败（${repoRoot}）`) }
+    }
+    details.push(`分支 ${meta.branch} 保留作 review 锚点（确认无需回溯后可 git -C ${repoRoot} branch -D ${meta.branch}）`);
+    results.push({ repoKey, result: residual.length > 0 ? 'partial' : 'cleaned', details, residual });
+  }
+  return { results };
+}