@jspg-ai/coding-bb 0.0.3-beta.21 → 0.0.3-beta.22

package/cbb/worktrees/_shared/scripts/find-target-worktree.js

@@ -1,96 +1,148 @@
-require('./silence-popup');
-/**
- * openspec-shared 目标需求名识别
- *
- * 唯一真源：cbb/worktrees/_shared/scripts/find-target-worktree.js
- * 由 scripts/sync-shared.js 展开到各 skill 的 scripts/ 下（extend / close / push）。
- *
- * 用法：node find-target-worktree.js <ws_root>
- *
- * 优先级：
- *   1. cwd 在 .worktrees/worktree-xxx/ 内 → 自动从路径反推
- *   2. .worktrees/ 下只有一个 worktree → 自动选用
- *   3. 多个 worktree → 按 mtime 倒序，第一个为推荐
- *
- * 输出：
- *   末行输出需求名（用于 AI agent 解析）
- *   多个时按 [1] xxx ⭐ / [2] yyy 列出
- *
- * 退出码：
- *   0 - 唯一识别（自动或唯一）
- *   1 - 多个 worktree，需用户输入
- *   2 - 无 worktree
- */
-
-const { execSync } = require('child_process');
-const fs = require('fs');
-const path = require('path');
-
-const wsRoot = process.argv[2];
-
-if (!wsRoot) {
-  console.error('❌ 用法：node find-target-worktree.js <ws_root>');
-  process.exit(1);
-}
-
-// 优先级 1：cwd 反推
-const cwd = process.cwd();
-const cwdMatch = cwd.match(/\.worktrees[\\\/]worktree-([^\\\/]+)/);
-if (cwdMatch) {
-  const branch = cwdMatch[1];
-  console.log('✅ 从 cwd 反推需求名：' + branch);
-  console.log('---');
-  console.log(branch);
-  process.exit(0);
-}
-
-const worktreesDir = path.join(wsRoot, '.worktrees');
-if (!fs.existsSync(worktreesDir)) {
-  console.error('❌ .worktrees 目录不存在：' + worktreesDir);
-  console.error('   请先执行 cbb-worktree-init 创建 worktree');
-  console.log('---');
-  console.log('NO_WORKTREE');
-  process.exit(2);
-}
-
-// 列出所有 worktree-xxx 目录
-const entries = fs.readdirSync(worktreesDir, { withFileTypes: true })
-  .filter(e => e.isDirectory() && e.name.startsWith('worktree-'))
-  .map(e => ({
-    name: e.name.substring('worktree-'.length),
-    fullName: e.name,
-    path: path.join(worktreesDir, e.name),
-    mtime: fs.statSync(path.join(worktreesDir, e.name)).mtime.getTime(),
-  }));
-
-if (entries.length === 0) {
-  console.error('❌ 未找到任何 worktree');
-  console.error('   请先执行 cbb-worktree-init 创建 worktree');
-  console.log('---');
-  console.log('NO_WORKTREE');
-  process.exit(2);
-}
-
-// 优先级 2：唯一
-if (entries.length === 1) {
-  console.log('✅ 自动选用唯一 worktree：' + entries[0].name);
-  console.log('---');
-  console.log(entries[0].name);
-  process.exit(0);
-}
-
-// 优先级 3：多个 → 按 mtime 倒序
-entries.sort((a, b) => b.mtime - a.mtime);
-
-console.log('⚠️  检测到 ' + entries.length + ' 个 worktree（按最近修改排序）：');
-entries.forEach((e, i) => {
-  if (i === 0) {
-    console.log('  [' + (i + 1) + '] ' + e.name + '  ⭐ (推荐：最近修改)');
-  } else {
-    console.log('  [' + (i + 1) + '] ' + e.name);
-  }
-});
-console.log('请在对话中输入序号(1/2/3)或完整分支名：');
-console.log('---');
-console.log('MULTIPLE_WORKTREEES');
-process.exit(1);
+require('./silence-popup');
+/**
+ * openspec-shared 目标需求名识别
+ *
+ * 唯一真源：cbb/worktrees/_shared/scripts/find-target-worktree.js
+ * 由 scripts/sync-shared.js 展开到各 skill 的 scripts/ 下（extend / close / push）。
+ *
+ * 用法：node find-target-worktree.js <ws_root>
+ *
+ * 优先级（ADR 0002 双布局）：
+ *   1. cwd 在 .worktrees/worktree-xxx/ 内 → 自动从路径反推
+ *   2. 收集候选：worktree 目录（.worktrees/worktree-xxx）
+ *      + 本地布局（根 / .codespace/<app>/ 检出在非主干分支，本地模式进行中）
+ *      同一需求名两种布局共存时合并为一项（标 both）
+ *   3. 唯一候选 → 自动选用；多个 → 按 mtime 倒序列出（本地布局用分支检出时间）
+ *
+ * 输出：
+ *   末行输出需求名（用于 AI agent 解析）
+ *   多个时按 [1] xxx ⭐ / [2] yyy 列出
+ *
+ * 退出码：
+ *   0 - 唯一识别（自动或唯一）
+ *   1 - 多个候选，需用户输入
+ *   2 - 无候选（无 worktree 且无本地布局检出）
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const wsRoot = process.argv[2];
+
+if (!wsRoot) {
+  console.error('❌ 用法：node find-target-worktree.js <ws_root>');
+  process.exit(1);
+}
+
+function run(cmd, cwd) {
+  try {
+    return execSync(cmd, { cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+  } catch (e) { return null; }
+}
+
+function currentBranch(cwd) {
+  return run('git branch --show-current', cwd) || '';
+}
+
+/** 主干名（探测失败返回 null → 该仓库任何非空检出都视为候选） */
+function detectMain(cwd) {
+  const remotes = run('git remote', cwd);
+  if (remotes) {
+    const r = remotes.split(/\r?\n/)[0];
+    const sym = run('git symbolic-ref "refs/remotes/' + r + '/HEAD"', cwd);
+    if (sym) return sym.replace('refs/remotes/' + r + '/', '');
+  }
+  if (run('git rev-parse --verify --quiet refs/heads/main', cwd)) return 'main';
+  if (run('git rev-parse --verify --quiet refs/heads/master', cwd)) return 'master';
+  return null;
+}
+
+// 优先级 1：cwd 反推
+const cwd = process.cwd();
+const cwdMatch = cwd.match(/\.worktrees[\\\/]worktree-([^\\\/]+)/);
+if (cwdMatch) {
+  const branch = cwdMatch[1];
+  console.log('✅ 从 cwd 反推需求名：' + branch);
+  console.log('---');
+  console.log(branch);
+  process.exit(0);
+}
+
+// 优先级 2a：worktree 目录候选
+const candidates = new Map(); // name → { layouts: Set, mtime }
+
+const worktreesDir = path.join(wsRoot, '.worktrees');
+if (fs.existsSync(worktreesDir)) {
+  const entries = fs.readdirSync(worktreesDir, { withFileTypes: true })
+    .filter(e => e.isDirectory() && e.name.startsWith('worktree-'));
+  for (const e of entries) {
+    const name = e.name.substring('worktree-'.length);
+    const full = path.join(worktreesDir, e.name);
+    const item = candidates.get(name) || { layouts: new Set(), mtime: 0 };
+    item.layouts.add('worktree');
+    item.mtime = Math.max(item.mtime, fs.statSync(full).mtime.getTime());
+    candidates.set(name, item);
+  }
+}
+
+// 优先级 2b：本地布局候选（根 + .codespace/<app>/ 检出在非主干分支）
+function addLocalCandidate(name, cwdPath) {
+  if (!name) return;
+  const item = candidates.get(name) || { layouts: new Set(), mtime: 0 };
+  item.layouts.add('local');
+  try {
+    item.mtime = Math.max(item.mtime, fs.statSync(path.join(cwdPath, '.git')).mtime.getTime());
+  } catch (_) { /* .git 状态时间不可读则保持 */ }
+  candidates.set(name, item);
+}
+
+const rootMain = detectMain(wsRoot);
+const rootBranch = currentBranch(wsRoot);
+if (rootBranch && (!rootMain || rootBranch !== rootMain)) {
+  addLocalCandidate(rootBranch, wsRoot);
+}
+
+const codeDir = path.join(wsRoot, '.codespace');
+if (fs.existsSync(codeDir)) {
+  for (const app of fs.readdirSync(codeDir).sort()) {
+    const appDir = path.join(codeDir, app);
+    if (!fs.existsSync(path.join(appDir, '.git'))) continue;
+    const appMain = detectMain(appDir);
+    const appBranch = currentBranch(appDir);
+    if (appBranch && (!appMain || appBranch !== appMain)) {
+      addLocalCandidate(appBranch, appDir);
+    }
+  }
+}
+
+if (candidates.size === 0) {
+  console.error('❌ 未找到任何进行中的需求（无 worktree，且无仓库检出在非主干分支）');
+  console.error('   worktree 模式请先执行 cbb-worktree-init；本地模式请先执行 cbb-local-mode');
+  console.log('---');
+  console.log('NO_WORKTREE');
+  process.exit(2);
+}
+
+// 唯一候选 → 自动选用
+if (candidates.size === 1) {
+  const [name] = [...candidates.keys()];
+  const layouts = [...candidates.get(name).layouts].join('+');
+  console.log('✅ 自动选用唯一进行中需求：' + name + '（' + layouts + '）');
+  console.log('---');
+  console.log(name);
+  process.exit(0);
+}
+
+// 多候选 → 按 mtime 倒序列出
+const sorted = [...candidates.entries()].sort((a, b) => b[1].mtime - a[1].mtime);
+console.log('⚠️  检测到 ' + sorted.length + ' 个进行中的需求（按最近活动排序）：');
+sorted.forEach(([name, item], i) => {
+  const layouts = [...item.layouts].join('+');
+  const tag = i === 0 ? '  ⭐ (推荐：最近活动)' : '';
+  console.log('  [' + (i + 1) + '] ' + name + '（' + layouts + '）' + tag);
+});
+console.log('请在对话中输入序号(1/2/3)或完整分支名：');
+console.log('---');
+console.log('MULTIPLE_WORKTREEES');
+process.exit(1);

package/cbb/worktrees/_shared/scripts/install-git-hook.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * 向指定 git 仓库安装分支感知 pre-commit hook（ADR 0002）。
+ *
+ * 真源：cbb/lib/utils/githook.js 的 PRE_COMMIT_SOURCE（本文件为部署到业务空间的自包含副本，
+ * 改动必须两处同步——本仓库内改真源后同步本文件，勿只改其一）。
+ *
+ * 用法（二选一）：
+ *   CLI：node install-git-hook.js <repoPath...>   —— 对每个仓库安装，输出 HOOK_RESULT
+ *   require：installTo(repoPath) → 'installed' | 'updated' | 'skipped-not-git'
+ *
+ * 供 cbb-worktree-init 的 sync-repos.js 兜底 clone 后调用（cbb setup 已装过，此处幂等补齐）。
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const HOOK_MARKER = 'managed-by-cbb';
+const HOOK_FILE = 'pre-commit';
+const BACKUP_SUFFIX = '.cbb-backup';
+
+// 与 cbb/lib/utils/githook.js 的 buildPreCommitSource() 输出完全一致（构建时注入）
+const PRE_COMMIT_SOURCE = "#!/usr/bin/env node\n// managed-by-cbb v1 —— 分支感知提交防线（ADR 0002）\n// main 上：workspace 仓库只放行控制面白名单，应用仓库全拦；非 main 一律放行。\n// 绕过逃生口仅限用户显式 git commit --no-verify。\nconst { execSync } = require('child_process');\nconst fs = require('fs');\nfunction run(cmd) {\n  try { return execSync(cmd, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim(); }\n  catch (e) { return null; }\n}\nconst branch = run('git branch --show-current') || '';\n// 主干名：优先远端 HEAD 指向；探测失败按本地 main/master 存在性回退\nlet main = null;\nconst remotes = run('git remote');\nif (remotes) {\n  const r = remotes.split(/\\r?\\n/)[0];\n  const sym = run('git symbolic-ref \"refs/remotes/' + r + '/HEAD\"');\n  if (sym) main = sym.replace('refs/remotes/' + r + '/', '');\n}\nif (!main) {\n  if (run('git rev-parse --verify --quiet refs/heads/main')) main = 'main';\n  else if (run('git rev-parse --verify --quiet refs/heads/master')) main = 'master';\n}\n// 非主干（含 detached / 探测失败）→ 放行\nif (!main || branch !== main) process.exit(0);\n\n// 主干上的提交：收集 staged 变更（空提交放行）\nconst staged = run('git diff --cached --name-only') || '';\nconst files = staged.split(/\\r?\\n/).filter(Boolean);\nif (files.length === 0) process.exit(0);\n\n// 仓库类型：workspace 仓库 = 检出含 workspace-config.json\nconst isWorkspace = fs.existsSync('workspace-config.json');\n\nfunction deny(bad) {\n  console.error('[cbb-guard] 主干上拦截载荷提交（ADR 0002）：');\n  bad.forEach(f => console.error('  ' + f));\n  console.error('需求载荷须在需求分支上提交：本地模式先 git checkout -b <需求名>；worktree 模式在 .worktrees/ 工作树内提交。');\n  console.error('控制面白名单：workspace-config.json / .gitignore / AGENTS.md / openspec/config.yaml / openspec/schemas/** / .cbb/**');\n  console.error('如确需在主干提交，须由用户显式 git commit --no-verify。');\n  process.exit(1);\n}\n\nif (isWorkspace) {\n  const EXACT = new Set(['workspace-config.json', '.gitignore', 'AGENTS.md', 'openspec/config.yaml']);\n  const PREFIXES = ['openspec/schemas/', '.cbb/'];\n  const bad = files.filter(f => !EXACT.has(f) && !PREFIXES.some(p => f.indexOf(p) === 0));\n  if (bad.length) deny(bad);\n} else {\n  deny(files);\n}\nprocess.exit(0);\n";
+
+function isCbbHookContent(content) {
+  return typeof content === 'string' && content.includes(HOOK_MARKER);
+}
+
+function resolveHooksDir(repoPath) {
+  const gitDir = path.join(repoPath, '.git');
+  if (!fs.existsSync(gitDir)) return null;
+  const st = fs.statSync(gitDir);
+  if (!st.isDirectory()) return null; // worktree 检出（.git 为文件）：hook 由主仓库承担
+  return path.join(gitDir, 'hooks');
+}
+
+function installTo(repoPath) {
+  const dir = resolveHooksDir(repoPath);
+  if (!dir) return 'skipped-not-git';
+
+  const hookPath = path.join(dir, HOOK_FILE);
+  fs.mkdirSync(dir, { recursive: true });
+
+  if (fs.existsSync(hookPath)) {
+    const prev = fs.readFileSync(hookPath, 'utf-8');
+    if (isCbbHookContent(prev)) {
+      if (prev !== PRE_COMMIT_SOURCE) fs.writeFileSync(hookPath, PRE_COMMIT_SOURCE);
+      return 'updated';
+    }
+    fs.writeFileSync(hookPath + BACKUP_SUFFIX, prev); // 用户自有 hook：备份后接管
+  }
+  fs.writeFileSync(hookPath, PRE_COMMIT_SOURCE);
+  try { fs.chmodSync(hookPath, 0o755); } catch (_) { /* Windows 无压力 */ }
+  return 'installed';
+}
+
+module.exports = { installTo, isCbbHookContent, PRE_COMMIT_SOURCE };
+
+// CLI 形式：node install-git-hook.js <repoPath...>
+if (require.main === module) {
+  const targets = process.argv.slice(2);
+  if (targets.length === 0) {
+    console.error('Usage: node install-git-hook.js <repoPath...>');
+    process.exit(1);
+  }
+  const results = targets.map(p => ({ path: p, status: installTo(p) }));
+  results.forEach(r => console.log((r.status === 'skipped-not-git' ? '⚠️ ' : '✅ ') + r.path + ' → ' + r.status));
+  console.log('HOOK_RESULT', JSON.stringify(results));
+  process.exit(0);
+}

package/cbb/worktrees/_shared/scripts/junction-ai-config.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * worktree 模式 AI 配置 junction（ADR 0002，防线 B）。
+ *
+ * 用法：node junction-ai-config.js <ws_root> <wt_path>
+ *
+ * 目的：让开发会话能开进 worktree（工作树内加载 AI 配置），同时保持
+ * 「单层安装」实质——配置唯一物理副本在空间根，cbb update 一处生效。
+ *
+ * 策略（规避 ADR 0001 否决时的状态污染）：
+ *   - 只 junction **只读内容子目录**（rules / skills / commands）：
+ *     工具向配置根写状态（如 settings.local.json）落在 worktree 自建的
+ *     物理（空壳）配置目录里，按项目隔离，不互相覆盖；
+ *   - 配置根目录本身在 worktree 侧是物理目录（不是链接）；
+ *   - .opencode/opencode.json 为文件（junction 不支持文件）：直接复制
+ *     （cbb update 后需重跑本脚本同步；worktree 为瞬态，影响可控）。
+ *
+ * 幂等：linkPath 已指向同一 target → skip；指向不同 → 重建；
+ *       存在同名**物理目录**（非链接）→ warn 跳过（不覆盖用户内容）。
+ *
+ * 退出码：0 成功（含全部 skip）；1 参数错误；2 执行失败。
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const wsRoot = process.argv[2];
+const wtPath = process.argv[3];
+
+if (!wsRoot || !wtPath) {
+  console.error('Usage: node junction-ai-config.js <ws_root> <wt_path>');
+  process.exit(1);
+}
+
+// 各工具的项目级配置根（存在才处理）与本包部署的内容子目录
+const CONFIG_ROOTS = ['.claude', '.qoder', '.opencode', '.workbuddy', '.trae'];
+const CONTENT_SUBDIRS = ['rules', 'skills', 'commands'];
+// 文件级内容（复制而非 junction）：opencode 的 instructions 登记
+const CONTENT_FILES = { '.opencode': ['opencode.json'] };
+
+const linked = [];
+const copied = [];
+const skipped = [];
+const warned = [];
+let hasFailure = false;
+
+/** 归一化 junction 目标路径（Windows readlink 返回 \\?\ 前缀） */
+function normLinkTarget(p) {
+  return path.resolve(String(p).replace(/^\\\\\?\\/, ''));
+}
+
+function linkDir(target, linkPath, label) {
+  if (fs.existsSync(linkPath)) {
+    const st = fs.lstatSync(linkPath);
+    if (st.isSymbolicLink()) {
+      const existing = normLinkTarget(fs.readlinkSync(linkPath));
+      if (existing === path.resolve(target)) {
+        skipped.push(label);
+        return;
+      }
+      fs.unlinkSync(linkPath); // 指向不同 → 重建
+    } else if (st.isDirectory()) {
+      warned.push(label + '（存在同名物理目录，未覆盖）');
+      return;
+    } else {
+      fs.unlinkSync(linkPath); // 同名文件，罕见，重建
+    }
+  }
+  fs.mkdirSync(path.dirname(linkPath), { recursive: true });
+  try {
+    if (process.platform === 'win32') {
+      fs.symlinkSync(path.resolve(target), linkPath, 'junction');
+    } else {
+      fs.symlinkSync(path.resolve(target), linkPath, 'dir');
+    }
+    linked.push(label);
+  } catch (e) {
+    console.error('❌ junction 失败 ' + label + ' — ' + e.message);
+    hasFailure = true;
+  }
+}
+
+function copyFile(target, dest, label) {
+  if (fs.existsSync(dest) && fs.existsSync(target) &&
+      fs.readFileSync(dest, 'utf-8') === fs.readFileSync(target, 'utf-8')) {
+    skipped.push(label);
+    return;
+  }
+  try {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(target, dest);
+    copied.push(label);
+  } catch (e) {
+    console.error('❌ 复制失败 ' + label + ' — ' + e.message);
+    hasFailure = true;
+  }
+}
+
+for (const root of CONFIG_ROOTS) {
+  const srcRoot = path.join(wsRoot, root);
+  if (!fs.existsSync(srcRoot) || !fs.statSync(srcRoot).isDirectory()) continue;
+
+  for (const sub of CONTENT_SUBDIRS) {
+    const src = path.join(srcRoot, sub);
+    if (!fs.existsSync(src) || !fs.statSync(src).isDirectory()) continue;
+    linkDir(src, path.join(wtPath, root, sub), root + '/' + sub);
+  }
+
+  for (const file of (CONTENT_FILES[root] || [])) {
+    const src = path.join(srcRoot, file);
+    if (!fs.existsSync(src) || !fs.statSync(src).isFile()) continue;
+    copyFile(src, path.join(wtPath, root, file), root + '/' + file);
+  }
+}
+
+if (linked.length === 0 && copied.length === 0 && skipped.length === 0 && warned.length === 0) {
+  console.log('ℹ️  空间根无 AI 配置目录，跳过（cbb setup 选择工具后再装）');
+} else {
+  if (linked.length) console.log('✅ junction：' + linked.join(', '));
+  if (copied.length) console.log('✅ 复制：' + copied.join(', '));
+  if (skipped.length) console.log('⏭️  已就绪：' + skipped.join(', '));
+  if (warned.length) console.log('⚠️  ' + warned.join('；'));
+}
+
+console.log('---');
+console.log('JUNCTION_RESULT', JSON.stringify({ linked, copied, skipped, warned, wt: wtPath }));
+process.exit(hasFailure ? 2 : 0);

package/cbb/worktrees/_shared/scripts/start-local.js

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+/**
+ * 本地模式开工（ADR 0002）：根 + 指定应用就地切需求分支。
+ *
+ * 用法：node start-local.js <ws_root> <branch> [--apps app1,app2] [--all-apps]
+ *
+ * 行为：
+ *   1. 前置自检：根与所有 .codespace/<app>/ 若任一检出在非主干分支 → 遗留态，
+ *      退出码 2（agent 应升级为用户决策：继续 / 收尾 / 升级 / 丢弃，不在本脚本内处理）
+ *   2. 参与仓库 = workspace + 应用子集：
+ *      - --apps a,b  → 指定应用（本地模式推荐：从需求语境提取涉及应用）
+ *      - --all-apps  → workspace-config.json 全量应用
+ *      - 缺省       → 仅 workspace（后续重跑幂等补齐，与 worktree-init 增补语义一致）
+ *   3. 每个仓库：
+ *      - 当前已在 <branch> → reused
+ *      - 分支存在（未检出）→ git checkout
+ *      - 否则 → git checkout -b <branch> <remote>/<main>（基线不取 HEAD，ADR 0002；
+ *        remote 不可用回退本地 main/master，再回退 HEAD）
+ *      - dirty 仓库切换失败 → 报错退出（不 stash 兜底，交给用户决策）
+ *   4. 参与的应用仓库幂等补装提交防线 hook（cbb setup 已装，此处兜底）
+ *
+ * 幂等：重跑同一 branch 安全（reused / checkout 跳过）。
+ *
+ * 退出码：
+ *   0 - 全部切换成功
+ *   1 - 参数错误
+ *   2 - 遗留态 / 部分切换失败
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const { installTo: installGitHook } = require('./install-git-hook');
+
+const wsRoot = process.argv[2];
+const branch = process.argv[3];
+
+if (!wsRoot || !branch) {
+  console.error('Usage: node start-local.js <ws_root> <branch> [--apps a,b] [--all-apps]');
+  process.exit(1);
+}
+
+function run(cmd, cwd) {
+  try {
+    return { ok: true, out: execSync(cmd, { cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim() };
+  } catch (e) {
+    return { ok: false, err: (e.stderr ? e.stderr.toString() : e.message || String(e)).trim() };
+  }
+}
+
+/** 主干名：symbolic-ref 远端 HEAD → 本地 main/master 回退 */
+function detectMain(cwd) {
+  const remotes = run('git remote', cwd);
+  if (remotes.ok && remotes.out) {
+    const r = remotes.out.split(/\r?\n/)[0];
+    const sym = run('git symbolic-ref "refs/remotes/' + r + '/HEAD"', cwd);
+    if (sym.ok && sym.out) return { remote: r, main: sym.out.replace('refs/remotes/' + r + '/', '') };
+  }
+  if (run('git rev-parse --verify --quiet refs/heads/main', cwd).ok) return { remote: null, main: 'main' };
+  if (run('git rev-parse --verify --quiet refs/heads/master', cwd).ok) return { remote: null, main: 'master' };
+  return { remote: null, main: null };
+}
+
+function currentBranch(cwd) {
+  const r = run('git branch --show-current', cwd);
+  return r.ok ? r.out : '';
+}
+
+// ── 1. 前置自检：遗留态检测 ───────────────────────────────
+// 「非主干」且「不是本次 branch」才是遗留（别的需求没收尾）；
+// 已检出在本次 branch 上 = 幂等补齐场景，放行（reused）。
+
+function isOnMain(cwd) {
+  const info = detectMain(cwd);
+  return info.main ? currentBranch(cwd) === info.main : false;
+}
+
+function isOnTarget(cwd) {
+  return currentBranch(cwd) === branch || isOnMain(cwd);
+}
+
+const leftovers = [];
+if (!isOnTarget(wsRoot)) leftovers.push({ name: 'workspace', branch: currentBranch(wsRoot) });
+const codeDir = path.join(wsRoot, '.codespace');
+if (fs.existsSync(codeDir)) {
+  for (const name of fs.readdirSync(codeDir).sort()) {
+    const appDir = path.join(codeDir, name);
+    if (fs.existsSync(path.join(appDir, '.git')) && !isOnTarget(appDir)) {
+      leftovers.push({ name, branch: currentBranch(appDir) });
+    }
+  }
+}
+if (leftovers.length > 0) {
+  console.error('❌ 遗留态：以下仓库检出在非主干分支，先由用户决策处理（继续/收尾/升级/丢弃）：');
+  leftovers.forEach(l => console.error('   - ' + l.name + ': ' + l.branch));
+  console.log('---');
+  console.log('LOCAL_START_FAILED', JSON.stringify({ reason: 'leftover', leftovers }));
+  process.exit(2);
+}
+
+// ── 2. 参与仓库集合 ───────────────────────────────────────
+
+let appNames = [];
+const argApps = process.argv.indexOf('--apps');
+const argAll = process.argv.includes('--all-apps');
+if (argApps >= 0) {
+  const raw = process.argv[argApps + 1] || '';
+  appNames = raw.split(',').map(s => s.trim()).filter(Boolean);
+} else if (argAll) {
+  try {
+    const config = JSON.parse(fs.readFileSync(path.join(wsRoot, 'workspace-config.json'), 'utf-8'));
+    appNames = (config.apps || []).map(a => a.name);
+  } catch (e) {
+    console.error('❌ 读取 workspace-config.json 失败：' + e.message);
+    process.exit(2);
+  }
+}
+
+const targets = [{ name: 'workspace', dir: wsRoot }];
+for (const name of appNames) {
+  const appDir = path.join(wsRoot, '.codespace', name);
+  if (!fs.existsSync(path.join(appDir, '.git'))) {
+    console.error('❌ 应用仓库不存在：.codespace/' + name + '（请检查 workspace-config.json 或先跑 cbb setup）');
+    process.exit(2);
+  }
+  targets.push({ name, dir: appDir });
+}
+
+// ── 3. 逐仓库切换 ─────────────────────────────────────────
+
+const results = [];
+let hasFailure = false;
+
+for (const t of targets) {
+  const cur = currentBranch(t.dir);
+  if (cur === branch) {
+    console.log('⏭️  ' + t.name + ': 已在 ' + branch + '（reused）');
+    results.push({ name: t.name, status: 'reused' });
+    continue;
+  }
+
+  const exists = run('git rev-parse --verify --quiet refs/heads/' + branch, t.dir).ok;
+  const info = detectMain(t.dir);
+  let cmd;
+  let base = 'HEAD';
+  if (exists) {
+    cmd = 'git checkout "' + branch + '"';
+    base = '(existing)';
+  } else {
+    if (info.remote && info.main) base = info.remote + '/' + info.main;
+    else if (info.main) base = info.main;
+    cmd = 'git checkout -b "' + branch + '" "' + base + '"';
+  }
+  const r = run(cmd, t.dir);
+  if (r.ok) {
+    console.log('✅ ' + t.name + ': ' + (exists ? 'checkout' : 'created from ' + base) + ' → ' + branch);
+    results.push({ name: t.name, status: exists ? 'switched' : 'created', base });
+  } else {
+    console.error('❌ ' + t.name + ': 切换失败 — ' + r.err);
+    results.push({ name: t.name, status: 'failed', error: r.err });
+    hasFailure = true;
+  }
+}
+
+// ── 4. 参与应用补装提交防线 hook（幂等）────────────────────
+
+const hookResults = [];
+for (const t of targets) {
+  if (t.name === 'workspace') continue; // 根仓库 hook 由 cbb setup 安装
+  hookResults.push({ name: t.name, status: installGitHook(t.dir) });
+}
+
+console.log('---');
+console.log('LOCAL_START_RESULT', JSON.stringify({
+  branch,
+  results,
+  hooks: hookResults,
+  worktreeHint: '如需升级隔离：重跑 cbb-worktree-init（分支已存在自动复用，worktree 从分支创建，提交随身带走）',
+}));
+process.exit(hasFailure ? 2 : 0);