sillyspec 3.26.11 → 3.26.13

package/src/verify-postcheck.js

@@ -15,7 +15,8 @@
  *           测试，避免 monorepo 全量测试超 gate timeout。
  */
 
-import { execSync, execFileSync } from 'child_process'
+import { execSync } from 'child_process'
+import { gitQuiet } from './git-helper.js'
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { join } from 'path'
 import { verifyApiParity } from './contract-matrix.js'
@@ -26,6 +27,18 @@ import { filterDeliverableFiles } from './worktree-apply.js'
 const TEST_TIMEOUT_MS = Number(process.env.SILLYSPEC_TEST_TIMEOUT_MS) || 10 * 60 * 1000
 const OUTPUT_TAIL_CHARS = 4000
 
+/**
+ * 行尾归一（坑 verify-modules-crlf-blanket-fallback，2026-08-20 实证）：Windows 仓的
+ * local.yaml 常为 CRLF（编辑器/CLI 写入），手写行扫描器的逐行正则里 `.` 不匹配 `\r`、
+ * `$`（无 m 标志）又要求真串尾——`\r` 残留行尾导致条目正则整条失配。实证受害：
+ * extractModules 返回 null（modules 映射恒失效 → 永远回退全量 → 600s 默认超时必炸）、
+ * extractKnownFailures 块式只捕获第一条。统一在解析入口归一，JS 的 `\r?\n` 拆分与
+ * yaml 库均兼容 LF 文本（零回归）。
+ */
+function normalizeLineEndings(text) {
+  return String(text || '').replace(/\r\n?/g, '\n')
+}
+
 /**
  * 从 local.yaml 文本提取 commands.test。
  * 轻量正则（与 worktree-deps/scan-postcheck 同风格，不引 yaml 依赖）：
@@ -123,7 +136,7 @@ export function computeFullFallbackReason({ strategy, modulesPresent, hitCount }
  */
 export function extractModules(yamlText) {
   if (!yamlText) return null
-  const lines = yamlText.split('\n')
+  const lines = normalizeLineEndings(yamlText).split('\n')
 
   // 定位 modules: 起始行（必须是顶层 key，行首无缩进或仅注释后顶层）
   let startIdx = -1
@@ -167,8 +180,15 @@ function parseFlowValue(flowText, key) {
   const m = flowText.match(re)
   if (!m) return null
   let v = m[1].trim()
-  if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
-    v = v.slice(1, -1)
+  if (v.startsWith('"') && v.endsWith('"')) {
+    // 双引号值剥壳后解开转义（坑 verify-modules-crlf-blanket-fallback 次生发现）：modules 的
+    // test 命令常含嵌套引号（node -e "…" / pytest "…"），yaml 源里写作 \"；此前只剥外层引号
+    // 不解 \\ 与 \"，解析结果残留字面反斜杠 → 命令直接坏。其余冷门转义（\n 等）按 YAML 规范
+    // 应真转义，但保守留字面（可见优于静默变换，测试命令不含它们）
+    v = v.slice(1, -1).replace(/\\(["\\])/g, '$1')
+  } else if (v.startsWith("'") && v.endsWith("'")) {
+    // 单引号值的 YAML 转义是 '' → '
+    v = v.slice(1, -1).replace(/''/g, "'")
   }
   return v.length > 0 ? v : null
 }
@@ -227,11 +247,14 @@ export function aggregateStatus(results) {
  */
 export function extractKnownFailures(yamlText) {
   if (!yamlText) return []
-  const inline = yamlText.match(/^known_failures:\s*\[([^\]]*)\]\s*(?:#.*)?$/m)
+  // CRLF 归一（坑 verify-modules-crlf-blanket-fallback）：块式正则的 `.+`/`\n?` 在 CRLF 行
+  // 间失配，只捕获到第一条豁免项就停——归一后整块捕获恢复
+  const yaml = normalizeLineEndings(yamlText)
+  const inline = yaml.match(/^known_failures:\s*\[([^\]]*)\]\s*(?:#.*)?$/m)
   if (inline) {
     return inline[1].split(',').map(s => s.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean)
   }
-  const block = yamlText.match(/^known_failures:\s*\n((?:[ \t]+-[ \t].+\n?)+)/m)
+  const block = yaml.match(/^known_failures:\s*\n((?:[ \t]+-[ \t].+\n?)+)/m)
   if (block) {
     return (block[1].match(/^[ \t]+-[ \t]+(.+)/gm) || [])
       .map(s => s.replace(/^[ \t]+-[ \t]+/, '').trim().replace(/^['"]|['"]$/g, '').replace(/#.*$/, '').trim())
@@ -381,44 +404,29 @@ function assertSafeRefSpec(refSpec) {
 /**
  * 在指定 cwd 跑 `git diff --name-only <refSpec>`，返回相对仓库根的文件列表。
  * git 不可用 / 非仓库 / ref 无效 → 返回 null（调用方 fallback）。
+ * QUAL-01 收口：本地 execFileSync 裸调 → git-helper gitQuiet（统一 safe.directory），timeout 30s 保留。
  */
 function runGitDiffNameOnly(cwd, refSpec) {
-  try {
-    const ref = refSpec ? assertSafeRefSpec(refSpec) : null
-    if (refSpec && !ref) return null
-    const args = ['diff', '--name-only']
-    if (ref) args.push(ref)
-    const out = execFileSync('git', args, {
-      cwd,
-      encoding: 'utf8',
-      timeout: 30 * 1000,
-      stdio: ['ignore', 'pipe', 'pipe'],
-    })
-    return out.split('\n').map(l => l.trim()).filter(Boolean)
-  } catch {
-    return null
-  }
+  const ref = refSpec ? assertSafeRefSpec(refSpec) : null
+  if (refSpec && !ref) return null
+  const args = ['diff', '--name-only']
+  if (ref) args.push(ref)
+  const out = gitQuiet(cwd, args, { timeout: 30 * 1000, trim: false })
+  if (out === null) return null
+  return out.split('\n').map(l => l.trim()).filter(Boolean)
 }
 
 /**
  * 在指定 cwd 跑 `git diff --name-status <refSpec>`，返回原始文本（调用方按行解析，
  * 保留状态字母 D/R/C 供删除探针识别删除/重命名）。git 不可用 / 非仓库 / ref 无效 → 返回 null。
+ * QUAL-01 收口：同上走 gitQuiet（trim:false 保留原始文本）。
  */
 function runGitDiffNameStatus(cwd, refSpec) {
-  try {
-    const ref = refSpec ? assertSafeRefSpec(refSpec) : null
-    if (refSpec && !ref) return null
-    const args = ['diff', '--name-status']
-    if (ref) args.push(ref)
-    return execFileSync('git', args, {
-      cwd,
-      encoding: 'utf8',
-      timeout: 30 * 1000,
-      stdio: ['ignore', 'pipe', 'pipe'],
-    })
-  } catch {
-    return null
-  }
+  const ref = refSpec ? assertSafeRefSpec(refSpec) : null
+  if (refSpec && !ref) return null
+  const args = ['diff', '--name-status']
+  if (ref) args.push(ref)
+  return gitQuiet(cwd, args, { timeout: 30 * 1000, trim: false })
 }
 
 /**
@@ -555,6 +563,11 @@ function resolveMainChangedFiles(cwd, changeName) {
  * }}
  */
 export function runVerifyTestCheck({ cwd, specBase, changeName = null, ctx = null }) {
+  // 信任边界声明（体检 SEC-02 核实）：本函数三处 execSync(command) 的命令只来源于
+  // ① 主仓 specBase（resolveSpecDir → 主仓 .sillyspec/local.yaml）② 跨仓仓根
+  // <repo>/.sillyspec/local.yaml——均为仓库自有配置（与 `npm test` 同信任级：跑测试
+  // 本就是执行项目代码）。永不读取 agent 可写的 worktree 副本（对照 worktree-deps.js
+  // SEC-01 的源级分流）；修改 yaml 来源时必须维持此边界。
   const localYamlPath = join(specBase, 'local.yaml')
   const yamlText = existsSync(localYamlPath) ? readFileSync(localYamlPath, 'utf8') : null
 

package/src/worktree-apply.js

@@ -12,7 +12,6 @@
  * 8. 成功后自动 cleanup
  */
 
-import { execFileSync } from 'child_process';
 import { existsSync, unlinkSync, writeFileSync, mkdtempSync, rmSync, readdirSync, readFileSync } from 'fs';
 import { join, resolve } from 'path';
 import { tmpdir } from 'os';
@@ -487,12 +486,17 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
     return applyByMerge(result, changeName, projectRoot, wm);
   }
 
-  // --- 4.5 校验：主工作区是否有「未提交」脏改动（未提交 dirty 是 git apply --3way 危险区，必须拦）---
-  // 分工：4.5（排除规则下当前 dirty）+ 5a（脏∩changedFiles）挡「未提交」dirty；5b 管「已提交」HEAD 分叉（已放宽，见下）。
-  // 实测：主干未提交 dirty 时，git apply --3way 报 `does not match index` 且行为不一致（可能报错/可能半应用，
-  // 哪怕脏文件与 patch 不重叠）——这是 Windows/autocrlf 的 CRLF 副作用（非 git 本质限制：
-  // autocrlf off 时 --3way 在不重叠 dirty 树能 Applied cleanly，on 时才报 does not match index）。
-  // 但仓库 CRLF 混用 + 规则13 要求 Windows 兼容，fail-loud 在 Windows 仍有据，故此处友好拦截，引导用户先 commit/stash。
+  // --- 4.5 校验：主工作区「未提交」脏文件是否与本次变更重叠（overlap-only 拦截）---
+  // 分工：4.5（排除规则下 dirty∩changedFiles）+ 5a（更宽口径的同一交集）挡「未提交」dirty 重叠；
+  // 5b 管「已提交」HEAD 分叉（已放宽）。
+  // 2026-08-20 放宽（原全量拦截 → 只拦重叠）：原「排除规则下任何未提交文件即整体拒绝」会把与本次
+  // 变更无关的脏文件也硬挡，用户被迫走 rescue cp 手动路径。重叠（dirtyFiles ∩ changedFiles，
+  // changedFiles 已含删除文件与 worktree 新增同名文件）才是 git apply 无法安全应用的实际危险区。
+  // 残余风险与兜底（Windows/autocrlf）：实测 autocrlf on 时 git apply --3way 对 dirty 工作区可报
+  // `does not match index`（哪怕脏文件与 patch 不重叠；autocrlf off 时能干净应用，非 git 本质限制）。
+  // 交集空前提下该失败是安全的：step7 catch → rollbackApply 只 checkout/删除 patch 涉及文件
+  // （这些文件 apply 前无未提交修改，还原 = apply 前状态），无关脏文件不在 patch/rollback 范围
+  // 不受影响 → fail-safe，报错后 stash 重试即可。放行时 warning 提示此路径。
   // 排除非交付物的元数据/文档 churn（execute 自身改的 + 多操作者常改的 agent 指引/文档），
   // 否则别人改 CLAUDE.md/docs/.claude → 判定 dirty → apply 误阻断（多操作者仓库高频踩坑）。
   // 注意：排除规则必须和 computeBaselineHash (worktree.js) 一致（虽已不比对 hash，仍用同一口径判当前 dirty）。
@@ -503,38 +507,47 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
     const staged = gitQuiet(projectRoot, ['diff', '--cached', ...exclude]) || '';
     const unstaged = gitQuiet(projectRoot, ['diff', ...exclude]) || '';
     const untracked = gitQuiet(projectRoot, ['ls-files', '--others', '--exclude-standard', ...exclude]) || '';
-    // 意图（与 computeBaselineHash 注释一致）：只挡「未提交 dirty」——git apply --3way 对 dirty 工作区不稳。
+    // 意图（与 computeBaselineHash 注释一致）：只看「未提交 dirty」——git apply --3way 对 dirty 工作区不稳。
     // 不比对 hash 是否等于 execute 启动时 baselineHash：主仓 dirty→clean（execute 期间 commit 无关文件）后
     // hash 必变，若仍比对会永久死锁（须手改 meta.baselineHash）。改判「排除规则下当前是否有未提交 dirty」。
     const hasUncommittedDirty = staged !== '' || unstaged !== '' || untracked !== '';
     if (hasUncommittedDirty) {
-      // 未提交 dirty 拦截：列脏文件 + 指引先 commit/stash（git --3way 对 dirty 工作区不稳，merge 同理，故不再提 --merge）
       const dirtyFiles = [...new Set(
         ((gitQuiet(projectRoot, ['diff', '--name-only', 'HEAD']) || '').split('\n').filter(Boolean))
           .concat((gitQuiet(projectRoot, ['ls-files', '--others', '--exclude-standard']) || '').split('\n').filter(Boolean))
       )].filter(f => !f.startsWith('.sillyspec/') && f !== 'meta.json');
-      // rescue：dirty 拦截触发时生成逐文件 cp 安全子集（旁路 git apply），写 result.rescueCommands 供 assess/打印器消费
-      const rescueDirty = computeRescueDirtyFiles(projectRoot);
-      result.rescueCommands = generateRescueCommands({
-        changedFiles,
-        dirtyFiles: rescueDirty,
-        hashMismatchFiles: result.hashMismatchFiles,
-        deletedFiles: result.deletedFiles,
-        worktreePath,
-        projectRoot,
-      });
-      result.errors.push(
-        `主工作区有未提交的改动，git apply 无法安全应用。\n` +
-        (dirtyFiles.length > 0 ? `未提交文件：\n  ${dirtyFiles.join('\n  ')}\n` : '') +
-        `请先提交或暂存这些改动，再重新 apply：\n  git add -A && git commit -m "..."   或   git stash\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') +
-            (result.rescueCommands.warnings.length > 0 ? '\n' + result.rescueCommands.warnings.map(w => `  ${w}`).join('\n') : '') +
-            `\n  （共 ${result.rescueCommands.cpFileCount} 个可安全 cp，${result.rescueCommands.excludedCount} 个被排除）\n`
-          : '')
-      );
-      if (!checkOnly) return result; // checkOnly 收集不短路（一次报全）；真实 apply 短路
+      const overlapDirty = dirtyFiles.filter(f => changedFiles.includes(f));
+      if (overlapDirty.length > 0) {
+        // 重叠拦截：只有与本次变更同文件的未提交改动才无法安全 apply（列重叠文件，非全部脏文件）
+        const rescueDirty = computeRescueDirtyFiles(projectRoot);
+        result.rescueCommands = generateRescueCommands({
+          changedFiles,
+          dirtyFiles: rescueDirty,
+          hashMismatchFiles: result.hashMismatchFiles,
+          deletedFiles: result.deletedFiles,
+          worktreePath,
+          projectRoot,
+        });
+        result.errors.push(
+          `主工作区以下未提交文件与本次 apply 的变更重叠，git apply 无法安全应用：\n  ${overlapDirty.join('\n  ')}\n` +
+          `请先提交或暂存这些改动，再重新 apply：\n  git add -A && git commit -m "..."   或   git stash\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') +
+              (result.rescueCommands.warnings.length > 0 ? '\n' + result.rescueCommands.warnings.map(w => `  ${w}`).join('\n') : '') +
+              `\n  （共 ${result.rescueCommands.cpFileCount} 个可安全 cp，${result.rescueCommands.excludedCount} 个被排除）\n`
+            : '')
+        );
+        if (!checkOnly) return result; // checkOnly 收集不短路（一次报全）；真实 apply 短路
+      } else {
+        // 无关脏文件放行（只校验重叠文件）：--3way 若因 autocrlf 报 does not match index 会被
+        // step7 catch 回滚（交集空前提下无损，见上注释），stash 后重试即可——不再硬挡 rescue 手动路径
+        result.warnings = (result.warnings || []).concat([
+          `主工作区有 ${dirtyFiles.length} 个与本次 apply 无关的未提交文件，已放行（只校验重叠文件）：` +
+          `${dirtyFiles.slice(0, 5).join(', ')}${dirtyFiles.length > 5 ? ' 等' : ''}` +
+          `——若 apply --3way 因 CRLF/autocrlf 报 does not match index，可 git stash 后重试`
+        ]);
+      }
     }
   }
 
@@ -656,6 +669,17 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
       // FR-06：解析 git 原始 stderr 提取冲突文件列表（不静默吞掉）
       const rawStderr = e.message || '';
       const rollback = rollbackApply(projectRoot, trackedPatchFiles, newPatchFiles, rawStderr);
+      // autocrlf 副作用单独点名：主仓无关未提交 dirty + CRLF 转换可触发 does not match index
+      // （非文件内容冲突，交集空时 step4.5 已放行到这里）——回滚无损，stash 后重试即可
+      if (/does not match index/i.test(rawStderr)) {
+        result.errors.push(
+          `apply --3way 失败（does not match index）：多为主仓未提交文件 + Windows autocrlf 的 CRLF 副作用触发，非文件内容冲突。\n` +
+          `已回滚工作区到 apply 前状态（无损，无关未提交文件未受影响）。\n` +
+          `处理：git stash 后重试 sillyspec worktree apply ${changeName}，或 --merge 兜底。`
+        );
+        if (rollback.error) result.warnings = (result.warnings || []).concat([`回滚警告: ${rollback.error}`]);
+        return result;
+      }
       result.errors.push(
         `apply --3way 冲突：以下文件与主干「已提交」推进重叠，无法自动合并：\n` +
         `  ${rollback.conflicts.length > 0 ? rollback.conflicts.join('\n  ') : '(未能获取冲突文件列表)'}\n` +
@@ -1174,9 +1198,9 @@ export function formatExecuteSummary({ changeName, stepsCompleted, stepsTotal, a
     // worktree 还在，用 baselineCommit 或 baseHash 做 diff
     try {
       const diffBase = meta.baselineCommit || meta.baseHash;
-      // execFileSync 数组形式：路径无需引号化（含空格也安全）；stdio stderr=ignore
-      // 替代 `2>/dev/null`（Windows cmd.exe 无法解析该重定向，导致 Windows 上恒抛错→Changed Files 空）
-      const filesRaw = execFileSync('git', ['-C', meta.worktreePath, 'diff', '--name-only', diffBase], { encoding: 'utf8', stdio: ['ignore','pipe','ignore'] });
+      // QUAL-01 收口：裸 execFileSync → git-helper git（stderr 由 helper stdio 配置吞掉，
+      // 替代 `2>/dev/null`——Windows cmd.exe 无法解析该重定向，导致 Windows 上恒抛错→Changed Files 空）
+      const filesRaw = git(meta.worktreePath, ['diff', '--name-only', diffBase], { timeout: 30000 });
       const files = filesRaw ? filesRaw.trim().split('\n').filter(Boolean) : [];
       if (files.length > 0) {
         lines.push(``);

package/src/worktree-deps.js

@@ -9,8 +9,8 @@
  */
 
 import { existsSync, readFileSync, realpathSync } from 'fs';
-import { join } from 'path';
-import { execSync, execFileSync } from 'child_process';
+import { join, isAbsolute, resolve as resolvePath, sep as pathSep } from 'path';
+import { execFileSync } from 'child_process';
 import { createHash } from 'crypto';
 
 const LOCKFILES = ['pnpm-lock.yaml', 'package-lock.json', 'yarn.lock'];
@@ -44,16 +44,28 @@ function detectLockfile(dir) {
   return null;
 }
 
-/** 读取 local.yaml 文本（specBase 优先，回退 worktreePath/.sillyspec；不读 process.cwd 避免环境配置泄漏）*/
-function readLocalYaml(specBase, worktreePath) {
-  const candidates = [
-    specBase ? join(specBase, 'local.yaml') : null,
-    worktreePath ? join(worktreePath, '.sillyspec', 'local.yaml') : null,
-  ].filter(Boolean);
-  for (const p of candidates) {
-    if (existsSync(p)) return readFileSync(p, 'utf8');
+/**
+ * 读取 local.yaml 文本（specBase 优先，回退 worktreePath/.sillyspec；不读 process.cwd 避免环境配置泄漏）。
+ * 返回 { text, source }——source 标记信任级（体检 SEC-01）：
+ *   - 'specBase'：主仓配置，可信（其 commands.install 允许执行，仍过白名单+元字符门）
+ *   - 'worktree'：worktree 内副本，agent/子代理可写区——只作 project.type / modules 等
+ *     只读探测，其 commands.install 永不执行（否则绕过 worktree-guard 的危险命令拦截）
+ */
+function readLocalYamlSourced(specBase, worktreePath) {
+  if (specBase) {
+    const p = join(specBase, 'local.yaml');
+    if (existsSync(p)) return { text: readFileSync(p, 'utf8'), source: 'specBase' };
   }
-  return null;
+  if (worktreePath) {
+    const p = join(worktreePath, '.sillyspec', 'local.yaml');
+    if (existsSync(p)) return { text: readFileSync(p, 'utf8'), source: 'worktree' };
+  }
+  return { text: null, source: null };
+}
+
+/** 兼容旧签名：只要文本 */
+function readLocalYaml(specBase, worktreePath) {
+  return readLocalYamlSourced(specBase, worktreePath).text;
 }
 
 /** 从 local.yaml 文本提取 commands.install（轻量正则，不引 yaml 依赖，与 scan-postcheck 一致）*/
@@ -93,6 +105,10 @@ export function inferInstallCommand(projectType, worktreePath, userInstall) {
     case 'maven':
       return 'mvn -o test';
     case 'gradle':
+      // win32 cmd.exe 跑不了 ./gradlew（体检 BUG-08 同型）：优先 gradlew.bat，否则全局 gradle
+      if (process.platform === 'win32') {
+        return existsSync(join(worktreePath, 'gradlew.bat')) ? 'gradlew.bat test' : 'gradle test';
+      }
       return './gradlew test';
     case 'python':
       // uv 优先（现代 Python 工具链，pyproject.toml/uv.lock 项目走 uv sync 建 .venv + 装依赖，
@@ -130,15 +146,80 @@ function tryLink(mainNodeModules, linkPath) {
   }
 }
 
-/** 执行 install 命令（带超时）*/
+/**
+ * 执行 install 命令（带超时）。
+ *
+ * 安全收口（体检 SEC-01）：commands.install 来自 local.yaml 配置，若经 execSync(shell)
+ * 原样执行，yaml 里的 `$(...)`/反引号/`;` 必然被解释——且 worktree 副本属 agent 可写区。
+ * 三道门：
+ *   1. 调用方保证来源可信（provisionDeps 只对 source==='specBase' 的 userInstall 走到这里）
+ *   2. 可执行前缀白名单（包管理器家族）
+ *   3. shell 元字符黑名单（win32 额外拦 %，cmd.exe 会展开 %VAR%），通过后拆 argv 数组执行不经 shell
+ *
+ * 链式命令支持（坑 worktree-install-whitelist-monorepo-chain，2026-08-20 实证）：monorepo 的
+ * commands.install 常为链式写法（`cd web && pnpm install` / `npm install && npm run build:pkg`），
+ * 旧实现整条过白名单 + 元字符门，`&&` 必拒 → depsStatus=failed → execute deps 门控卡死且无自愈
+ * 路径（改 local.yaml 成单命令对需要 post-install build 的 monorepo 不可行）。现按 `&&` 拆段
+ * 逐段校验执行：每段独立过白名单 + 元字符门（拆分后残余的单 `&`/`|`/`;` 仍被元字符门拦），
+ * 段内允许 `cd <相对子路径>`（resolve 后必须仍在 worktree 根内，防越界建产物/读外部），
+ * 全程 argv 数组执行不经 shell、任一段失败即停（&& 语义）。安全面不变：每个执行段仍是
+ * 白名单包管理器命令，`||`/管道/`;`/后台均不支持。
+ */
+const INSTALL_BINARY_WHITELIST = /^(?:\.\/)?(?:pnpm|npm|yarn|bun|mvn|gradle|gradlew|uv|pip|pip3|python|python3|poetry|make)(?:\.cmd|\.bat|\.exe)?(?:\s|$)/;
+const SHELL_METACHARS = /[;&|<>$`\n]/;
+const WIN_SHELL_METACHARS = /[;&|<>$`\n%]/;
+const CD_SEGMENT_RE = /^cd\s+([^\s]+)$/;
+
 function tryInstall(cmd, cwd, timeout) {
-  try {
-    execSync(cmd, { cwd, timeout, stdio: ['pipe', 'pipe', 'pipe'] });
-    return { ok: true };
-  } catch (e) {
-    const msg = e.killed ? `timeout after ${timeout}ms` : ((e.stderr && e.stderr.toString()) || e.message);
-    return { ok: false, error: `${cmd} failed: ${msg}` };
+  const trimmed = String(cmd || '').trim();
+  if (!trimmed) {
+    return { ok: false, error: 'install 命令为空' };
+  }
+  const metaRe = process.platform === 'win32' ? WIN_SHELL_METACHARS : SHELL_METACHARS;
+  // && 拆段（单段命令与原路径完全一致，零回归）；空段（`a &&`/`&& b`）视为畸形命令拒绝
+  const segments = trimmed.split('&&').map(s => s.trim());
+  if (segments.some(s => s === '')) {
+    return { ok: false, error: `install 链式命令含空段，拒绝执行: ${trimmed}` };
   }
+  let curCwd = cwd;
+  const root = resolvePath(cwd);
+  const planned = [];
+  for (const seg of segments) {
+    // 白名单先于元字符（保持原判定顺序）：`curl … | sh` 报非白名单而非元字符，
+    // `npm install; rm …` 过白名单后被元字符门拦——两类拒绝语义与原实现一致
+    const cd = seg.match(CD_SEGMENT_RE);
+    if (!cd && !INSTALL_BINARY_WHITELIST.test(seg)) {
+      return { ok: false, error: `install 命令不在包管理器白名单内，拒绝执行: ${seg}（支持 && 链式与 cd <子目录> 段，各执行段仍须为白名单包管理器命令）` };
+    }
+    if (metaRe.test(seg)) {
+      return { ok: false, error: `install 命令段含 shell 元字符，拒绝执行: ${seg}（链式仅支持 &&；|| / 管道 / ; / 后台不支持）` };
+    }
+    if (cd) {
+      const target = resolvePath(curCwd, cd[1]);
+      if (target !== root && !target.startsWith(root + pathSep)) {
+        return { ok: false, error: `install 命令的 cd 段越出 worktree 根，拒绝执行: ${seg}（cwd ${cwd}）` };
+      }
+      curCwd = target;
+      continue;
+    }
+    planned.push(seg);
+  }
+  for (const seg of planned) {
+    const argv = seg.split(/\s+/);
+    try {
+      if (process.platform === 'win32') {
+        // Windows 包管理器是 .cmd 垫片，无 shell 的 spawn 无法解析——经 cmd.exe /c 传参；
+        // 元字符（含 %）已拦，残余风险与 tryLink 的 mklink 同款
+        execFileSync('cmd.exe', ['/c', ...argv], { cwd: curCwd, timeout, stdio: ['pipe', 'pipe', 'pipe'] });
+      } else {
+        execFileSync(argv[0], argv.slice(1), { cwd: curCwd, timeout, stdio: ['pipe', 'pipe', 'pipe'] });
+      }
+    } catch (e) {
+      const msg = e.killed ? `timeout after ${timeout}ms` : ((e.stderr && e.stderr.toString()) || e.message);
+      return { ok: false, error: `${seg} failed (cwd ${curCwd}): ${msg}` };
+    }
+  }
+  return { ok: true };
 }
 
 /** 目录是否含 nodejs 标记（package.json 或任一 lockfile）——识别 monorepo 里的 nodejs 子模块 */
@@ -174,6 +255,16 @@ function extractModulePaths(yamlText) {
   return [...new Set(paths)];
 }
 
+/**
+ * modules 块 path 安全校验（体检 SEC-07）：只允许 worktree 内的相对子路径——
+ * 拒绝绝对路径与 `..` 段，防止 local.yaml 配置把 junction/symlink 建到 worktree 之外。
+ */
+function isSafeModulePath(p) {
+  if (!p || isAbsolute(p)) return false;
+  const segs = p.split(/[\\/]+/);
+  return !segs.includes('..');
+}
+
 /**
  * 对单个子模块目录 tryLink main 的 node_modules → wt 的 node_modules（modules 子模块专用）。
  * 仅走 link 快路径（不 install——子模块 install 慢且易失败；lockfile 不一致时交给用户 pnpm install）。
@@ -211,12 +302,17 @@ function linkOneDir(wtDir, mainDir) {
 export function provisionDeps(worktreePath, mainCwd, opts = {}) {
   const { specBase = null, timeout = DEFAULT_TIMEOUT_MS, force = false } = opts;
   const depsCheckedAt = new Date().toISOString();
-  const yamlText = readLocalYaml(specBase, worktreePath);
+  const { text: yamlText, source: yamlSource } = readLocalYamlSourced(specBase, worktreePath);
   const wtHash = lockfileHash(worktreePath);
 
   // ── 1. 根目录供给 ──
   const projectType = detectProjectType(worktreePath, specBase);
-  const userInstall = extractUserInstall(yamlText);
+  // SEC-01：commands.install 只信主仓 specBase 的 local.yaml——worktree 副本是 agent 可写区，
+  // 其 install 命令若执行等于绕过 worktree-guard 的危险命令拦截
+  const userInstall = yamlSource === 'specBase' ? extractUserInstall(yamlText) : null;
+  if (yamlSource === 'worktree' && extractUserInstall(yamlText)) {
+    console.warn('⚠️ worktree 内 local.yaml 的 commands.install 被忽略（agent 可写区，只信主仓 .sillyspec/local.yaml）');
+  }
   const installCmd = inferInstallCommand(projectType, worktreePath, userInstall);
 
   let result;
@@ -257,6 +353,10 @@ export function provisionDeps(worktreePath, mainCwd, opts = {}) {
   const modulePaths = extractModulePaths(yamlText);
   const moduleResults = [];
   for (const mp of modulePaths) {
+    if (!isSafeModulePath(mp)) {
+      moduleResults.push({ path: mp, status: 'skipped', reason: 'path 越界（绝对路径或 .. 段），拒绝 link' });
+      continue;
+    }
     const wtDir = join(worktreePath, mp);
     const mainDir = mainCwd ? join(mainCwd, mp) : null;
     if (!existsSync(wtDir) || !mainDir || !hasNodeMarker(wtDir)) continue;

package/src/worktree.js

@@ -8,7 +8,7 @@
  * 分支命名：sillyspec/<change-name>
  */
 
-import { execSync, execFileSync } from 'child_process';
+import { execFileSync } from 'child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, readdirSync, statSync, lstatSync, readlinkSync, unlinkSync } from 'fs';
 import { join, resolve, dirname, relative, isAbsolute } from 'path';
 import { createHash } from 'crypto';
@@ -463,6 +463,12 @@ export class WorktreeManager {
       if (!check.supported) {
         throw new Error(`git worktree add 失败: ${e.stderr || e.message}\n\n${check.reason ? `原因: ${check.reason}` : ''}\n建议: 升级 git 到 >= 2.15；或运行 \`sillyspec worktree doctor --fix\` 检查 worktree 状态。`);
       }
+      // 体检 BUG-16 并发竞态防御：多 agent 同时首建同名 change 时，败者的 add 失败可能只是
+      // 「赢家刚建成目录/分支」。此时降级 in-place 会造成一个 worktree + 一个 in-place 的
+      // 分裂状态（两 agent 各写各的基线）——先重查，并发赢家已建成则按 already exists 抛错。
+      if (existsSync(worktreePath) || gitQuiet(this.cwd, ['rev-parse', '--verify', `refs/heads/${branch}`])) {
+        throw new Error(`worktree already exists: ${name}（并发创建，另一进程已抢先建成，本进程不降级 in-place）. Run cleanup first.`);
+      }
       // sandbox/permission fallback: 降级为 in-place + baseline protection
       console.log(`⚠️  git worktree add 失败（可能是沙箱权限限制），降级为 in-place 模式 + baseline protection`);
       console.log(`   原因: ${e.stderr || e.message}`);
@@ -928,7 +934,11 @@ export class WorktreeManager {
     const residual = [];
     if (!isInPlace && existsSync(worktreePath)) residual.push(`worktree dir: ${worktreePath}`);
     if (existsSync(metaDir)) residual.push(`meta dir: ${metaDir}`);
-    if (!isInPlace && gitQuiet(this.cwd, ['worktree', 'list'], { timeout: 30000 })?.includes(worktreePath)) {
+    // 斜杠方向归一后比较（体检 BUG-07）：Windows 下 git worktree list 输出正斜杠、
+    // worktreePath 是反斜杠，直接 includes 恒 false → 残留场景漏报、cleanup 误报 cleaned
+    const toPosixNorm = (p) => String(p || '').replace(/\\/g, '/').toLowerCase()
+    const wtListOut = gitQuiet(this.cwd, ['worktree', 'list'], { timeout: 30000 })
+    if (!isInPlace && wtListOut && toPosixNorm(wtListOut).includes(toPosixNorm(worktreePath))) {
       residual.push('git worktree list still references this worktree');
     }
     if (residual.length > 0) {
@@ -1033,11 +1043,32 @@ export class WorktreeManager {
    *     不传则全量扫（兼容现有行为）。
    * @returns {{ issues: Array<{ type: string, name: string, detail: string, fixable: boolean }>, fixed: string[], unfixable: string[] }}
    */
-  doctor({ fix = false, staleHours = 24, changeName = null } = {}) {
+  async doctor({ fix = false, staleHours = 24, changeName = null } = {}) {
     const issues = [];
     const fixed = [];
     const unfixable = [];
 
+    // 活跃变更注册表（坑 doctor-fix-orphan-branch-parallel-active，2026-08-20 实证）：孤儿分支
+    // 判定原只看本地 meta 目录注册表（metaNames），与变更活跃态的权威注册表（进度库 changes 表）
+    // 数据源不一致——并行会话的活跃变更（meta 已清/in-place/平台模式 meta 在别处）分支会被全局
+    // doctor --fix 误删。删分支前交叉核对：分支名 ∈ 活跃变更 → 保留（fixable:false 提示人工确认）。
+    // 先探 DB 文件存在再实例化 ProgressManager（坑7 读路径建库：_ensureDB 不存在会建库污染）。
+    // null = 进度库存在但读失败（无法判定活跃态，保守不自动删）；空 Set = 无库/无活跃变更
+    // （git-only 工作流零回归，孤儿分支照删）。
+    let activeChanges = null;
+    try {
+      const specBaseOfWt = dirname(dirname(this.worktreeBase)); // <specBase>（.runtime/worktrees 上两级）
+      if (existsSync(join(specBaseOfWt, '.runtime', 'sillyspec.db'))) {
+        const { ProgressManager } = await import('./progress.js');
+        activeChanges = new Set(new ProgressManager({ specDir: specBaseOfWt }).listChanges(this.cwd));
+      } else {
+        activeChanges = new Set();
+      }
+    } catch (e) {
+      console.warn(`⚠️ doctor 进度库读取失败，孤儿分支的活跃态交叉核对不可用（保守不自动删）: ${e.message}`);
+      activeChanges = null;
+    }
+
     // 1. 列出 git worktree list 中的条目
     let gitWorktreeList = [];
     try {
@@ -1167,16 +1198,30 @@ export class WorktreeManager {
       }
     }
 
-    // 5. 检查 SillySpec 分支残留
+    // 5. 检查 SillySpec 分支残留（活跃变更交叉核对，见方法头 activeChanges 注释）
     try {
-      const branches = execFileSync('git', ['branch', '--list', `${BRANCH_PREFIX}*`], { cwd: this.cwd, encoding: 'utf8', stdio: ['pipe','pipe','pipe'] }).trim();
+      // QUAL-01 收口：裸 execFileSync → git-helper git（原调用点未传 timeout，统一入口默认 5s 足够 branch --list）
+      const branches = git(this.cwd, ['branch', '--list', `${BRANCH_PREFIX}*`]);
       if (branches) {
         for (const line of branches.split('\n').filter(Boolean)) {
           const branch = line.replace(/^\*?\s+/, '').trim();
           const name = branch.replace(BRANCH_PREFIX, '');
           if (changeName && name !== changeName) continue; // --change 过滤：仅扫指定 change
           if (!metaNames.has(name)) {
-            issues.push({ type: 'orphan-branch', name, detail: `分支残留（无对应 meta）: ${branch}`, fixable: true });
+            if (activeChanges && activeChanges.has(name)) {
+              // 变更仍注册活跃：分支大概率是并行会话在用（或 apply 后被 review 引用审计保护保留）
+              // ——数据源不一致的正解是保留 + 人工确认，不是删
+              issues.push({ type: 'active-branch', name, fixable: false,
+                detail: `分支 ${branch} 无本地 meta，但变更 "${name}" 在进度库仍注册为活跃（并行会话在跑 / meta 已清分支在用）——保留。确认废弃后：先归档/结束该变更，或手动 git branch -D ${branch}` });
+              continue;
+            }
+            if (activeChanges === null) {
+              // 进度库读失败：无法判定活跃态，保守不自动删（宁可漏删不可误删并行会话分支）
+              issues.push({ type: 'orphan-branch', name, fixable: false,
+                detail: `分支疑似残留（无对应 meta，且进度库不可读无法交叉核对活跃态）: ${branch}——保守不自动删，人工确认后 git branch -D ${branch}` });
+              continue;
+            }
+            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}`); }
             }
@@ -1357,7 +1402,8 @@ export class WorktreeManager {
       if (staged) {
         try {
           // 用 Buffer 模式读取，避免二进制 patch 被 UTF-8 解码损坏
-          const patchBuf = execFileSync('git', ['diff', '--cached', '--binary'], { cwd: mainCwd, stdio: ['pipe','pipe','pipe'] });
+          // QUAL-01 收口：git-helper 新增 encoding:'buffer' 支持（二进制输出专用，跳过 trim）
+          const patchBuf = git(mainCwd, ['diff', '--cached', '--binary'], { encoding: 'buffer', timeout: 30000 });
           if (patchBuf && patchBuf.length > 0) {
             const patchFile = join(worktreePath, '.sillyspec-baseline-staged.patch');
             try {
@@ -1379,8 +1425,8 @@ export class WorktreeManager {
       const unstaged = gitQuiet(mainCwd, ['diff', '--name-only'], { timeout: 30000 }) || '';
       if (unstaged) {
         try {
-          // 用 Buffer 模式读取，避免二进制 patch 被 UTF-8 解码损坏
-          const patchBuf = execFileSync('git', ['diff', '--binary'], { cwd: mainCwd, stdio: ['pipe','pipe','pipe'] });
+          // 用 Buffer 模式读取，避免二进制 patch 被 UTF-8 解码损坏（QUAL-01 收口，同上）
+          const patchBuf = git(mainCwd, ['diff', '--binary'], { encoding: 'buffer', timeout: 30000 });
           if (patchBuf && patchBuf.length > 0) {
             const patchFile = join(worktreePath, '.sillyspec-baseline-unstaged.patch');
             try {

package/.npmrc-publish

@@ -1,2 +0,0 @@
-//registry.npmjs.org/:_authToken=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
-always-auth=true