sillyspec 3.25.9 → 3.26.0

package/src/worktree.js

@@ -8,12 +8,13 @@
  * 分支命名：sillyspec/<change-name>
  */
 
-import { execSync } from 'child_process';
+import { execSync, execFileSync } from 'child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, readdirSync, statSync, lstatSync, readlinkSync, unlinkSync } from 'fs';
-import { join, resolve, dirname } from 'path';
+import { join, resolve, dirname, relative, isAbsolute } from 'path';
 import { createHash } from 'crypto';
-import { provisionDeps, lockfileHash } from './worktree-deps.js';
+import { provisionDeps, checkDepsFreshness } from './worktree-deps.js';
 import { writeAtomicSync } from './fs-atomic.js';
+import { git, gitQuiet } from './git-helper.js';
 
 // meta.json 会被 hook 进程与其它 CLI 进程并发读取（worktree-guard / getMeta / create 幽灵判定），
 // 必须原子写：半截 JSON 会让 getMeta 返回 null → 触发幽灵 worktree 强删（可能丢 gitignored 改动）。
@@ -39,9 +40,9 @@ const _mainRepoRootByCwd = new Map();
  */
 export function detectIsolation(cwd = process.cwd()) {
   try {
-    const gitDir = execSync('git rev-parse --git-dir', { cwd, encoding: 'utf8', stdio: ['pipe','pipe','pipe'] }).trim();
-    const gitCommonDir = execSync('git rev-parse --git-common-dir', { cwd, encoding: 'utf8', stdio: ['pipe','pipe','pipe'] }).trim();
-    const superProject = gitQuiet(cwd, 'rev-parse --show-superproject-working-tree');
+    const gitDir = git(cwd, ['rev-parse', '--git-dir']);
+    const gitCommonDir = git(cwd, ['rev-parse', '--git-common-dir']);
+    const superProject = gitQuiet(cwd, ['rev-parse', '--show-superproject-working-tree']);
 
     const inWorktree = gitDir !== gitCommonDir && !superProject;
     const inSubmodule = !!superProject;
@@ -60,25 +61,13 @@ export function detectIsolation(cwd = process.cwd()) {
 export function checkWorktreeDirIgnored(cwd = process.cwd()) {
   const relPath = WORKTREES_REL;
   try {
-    execSync(`git check-ignore -q ${relPath}`, { cwd, encoding: 'utf8', stdio: ['pipe','pipe','pipe'] });
+    git(cwd, ['check-ignore', '-q', relPath]);
     return { ignored: true, path: relPath };
   } catch {
     return { ignored: false, path: relPath };
   }
 }
 
-function git(cwd, args) {
-  return execSync(`git ${args}`, { cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
-}
-
-function gitQuiet(cwd, args) {
-  try {
-    return execSync(`git ${args}`, { cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
-  } catch {
-    return null;
-  }
-}
-
 /**
  * 检测 worktree base（主仓库 HEAD）与 origin 默认分支的同步状态（只读：不 ff、不改 HEAD）。
  * 替代旧的 fetch + merge --ff-only：旧逻辑分叉时 ff 失败被静默吞（syncStatus=failed），
@@ -93,12 +82,12 @@ export function computeBaseSync(cwd, baseHash) {
   const diag = { status: 'unknown', defaultBranch: null, behind: 0, ahead: 0 };
   // 推断默认分支：优先 origin/HEAD 指向的真实分支名（修复旧 339-342 的运算符优先级 bug
   // ——旧代码在 origin/HEAD 存在时恒返回 'main'，丢弃 symbolic-ref 的真实结果）。
-  const headRef = gitQuiet(cwd, 'symbolic-ref refs/remotes/origin/HEAD --short');
+  const headRef = gitQuiet(cwd, ['symbolic-ref', 'refs/remotes/origin/HEAD', '--short']);
   let defaultBranch = headRef ? headRef.replace('origin/', '') : null;
   if (!defaultBranch) {
     // fallback：origin/HEAD 未设置时，探测常见默认分支是否存在
     for (const cand of ['main', 'master']) {
-      if (gitQuiet(cwd, `rev-parse --verify --quiet refs/remotes/origin/${cand}`)) {
+      if (gitQuiet(cwd, ['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${cand}`])) {
         defaultBranch = cand;
         break;
       }
@@ -108,15 +97,15 @@ export function computeBaseSync(cwd, baseHash) {
   diag.defaultBranch = defaultBranch;
 
   // best-effort fetch（只更新 remote-tracking，不改工作区/HEAD/分支；失败静默降级用缓存）
-  gitQuiet(cwd, 'fetch origin --quiet');
-  const remoteHead = gitQuiet(cwd, `rev-parse --verify --quiet refs/remotes/origin/${defaultBranch}`);
+  gitQuiet(cwd, ['fetch', 'origin', '--quiet'], { timeout: 60000 });
+  const remoteHead = gitQuiet(cwd, ['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${defaultBranch}`]);
   if (!baseHash || !remoteHead) return diag;
   if (baseHash === remoteHead) {
     diag.status = 'up-to-date';
     return diag;
   }
-  const behind = Number(gitQuiet(cwd, `rev-list --count ${baseHash}..${remoteHead}`) || 0);
-  const ahead = Number(gitQuiet(cwd, `rev-list --count ${remoteHead}..${baseHash}`) || 0);
+  const behind = Number(gitQuiet(cwd, ['rev-list', '--count', `${baseHash}..${remoteHead}`]) || 0);
+  const ahead = Number(gitQuiet(cwd, ['rev-list', '--count', `${remoteHead}..${baseHash}`]) || 0);
   diag.behind = behind;
   diag.ahead = ahead;
   diag.status = (behind > 0 && ahead > 0) ? 'diverged' : (behind > 0 ? 'behind' : 'ahead');
@@ -179,10 +168,10 @@ export function computeBaselineHash(cwd) {
   //   - docs/：文档（非代码交付物）
   //   - CLAUDE.md：根 agent 指引（多操作者常改）
   // 必须和 applyWorktree step 4.5 (worktree-apply.js) 使用相同的排除规则。
-  const exclude = '-- . ":(exclude).sillyspec/" ":(exclude).claude/" ":(exclude)docs/" ":(exclude)CLAUDE.md"';
-  const staged = gitQuiet(cwd, `diff --cached ${exclude}`) || '';
-  const unstaged = gitQuiet(cwd, `diff ${exclude}`) || '';
-  const untracked = gitQuiet(cwd, `ls-files --others --exclude-standard ${exclude}`) || '';
+  const exclude = ['--', '.', ':(exclude).sillyspec/', ':(exclude).claude/', ':(exclude)docs/', ':(exclude)CLAUDE.md'];
+  const staged = gitQuiet(cwd, ['diff', '--cached', ...exclude], { timeout: 30000 }) || '';
+  const unstaged = gitQuiet(cwd, ['diff', ...exclude], { timeout: 30000 }) || '';
+  const untracked = gitQuiet(cwd, ['ls-files', '--others', '--exclude-standard', ...exclude], { timeout: 30000 }) || '';
   const raw = `staged:${staged}
 unstaged:${unstaged}
 untracked:${untracked}`;
@@ -208,7 +197,7 @@ function validateChangeName(changeName) {
  */
 export function isGitWorktreeSupported(cwd = process.cwd()) {
   try {
-    const raw = execSync('git --version', { cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    const raw = git(cwd, ['--version']);
     const match = raw.match(/git version (\d+)\.(\d+)/);
     if (!match) return { supported: false, version: raw, reason: 'cannot parse version' };
     const major = parseInt(match[1], 10);
@@ -222,6 +211,31 @@ export function isGitWorktreeSupported(cwd = process.cwd()) {
   }
 }
 
+/**
+ * 复制单个 untracked 条目到 worktree（baseline overlay 用）。
+ *
+ * 防御目录：untracked 项若是目录（如 Claude Code agent worktree 隔离目录 .worktrees/<hash>/），
+ * readFileSync 会 EISDIR → 整个 overlay fail-fast。目录跳过（overlay 只同步文件层未提交改动，
+ * 目录结构由后续文件写入的 mkdirSync 重建）。坑 execute-worktree-overlay-untracked-dir-eisdir。
+ *
+ * @param {string} src 主仓库源路径
+ * @param {string} dst worktree 目标路径
+ * @returns {{status:'copied'|'skipped-dir'|'missing'|'error', error?:string}}
+ */
+export function copyUntrackedEntry(src, dst) {
+  if (!existsSync(src)) return { status: 'missing' };
+  let st;
+  try { st = statSync(src); } catch { return { status: 'missing' }; }
+  if (st.isDirectory()) return { status: 'skipped-dir' };
+  try {
+    mkdirSync(dirname(dst), { recursive: true });
+    writeFileSync(dst, readFileSync(src));
+    return { status: 'copied' };
+  } catch (e) {
+    return { status: 'error', error: e.message };
+  }
+}
+
 export class WorktreeManager {
   constructor({ cwd, worktreeDir } = {}) {
     this.cwd = cwd || process.cwd();
@@ -254,7 +268,7 @@ export class WorktreeManager {
       // existsSync/statSync 会相对 process.cwd() 解析——当 process.cwd 是另一个 git 仓库
       // （未 chdir 的脚本、或 CLI 在别处跑）时，worktreeBase 会错解析到 process.cwd 仓库，
       // getMeta 读错位置返回 null。resolve() 对绝对参数原样返回、对相对参数相对 this.cwd 解析，两者皆稳。
-      const commonDir = gitQuiet(this.cwd, 'rev-parse --git-common-dir');
+      const commonDir = gitQuiet(this.cwd, ['rev-parse', '--git-common-dir']);
       if (commonDir) {
         const absCommonDir = resolve(this.cwd, commonDir);
         if (existsSync(absCommonDir) && statSync(absCommonDir).isDirectory()) {
@@ -324,7 +338,7 @@ export class WorktreeManager {
       // 只恢复 meta 引用，不触碰文件系统。
       return this._recoverNativeWorktreeMeta(name, {
         worktreePath: this.cwd,
-        branch: gitQuiet(this.cwd, 'symbolic-ref --short HEAD') || 'detached',
+        branch: gitQuiet(this.cwd, ['symbolic-ref', '--short', 'HEAD']) || 'detached',
       });
     }
 
@@ -345,7 +359,7 @@ export class WorktreeManager {
       // 否则会丢失 execute 期间未 commit 的代码（不可恢复，3.22.4 修复）。
       if (!this.getMeta(name)) {
         let uncommitted = '';
-        try { uncommitted = git(worktreePath, 'status --porcelain') } catch {}
+        try { uncommitted = git(worktreePath, ['status', '--porcelain'], { timeout: 30000 }) } catch {}
         if (uncommitted.trim()) {
           throw new Error(
             `检测到幽灵 worktree（无 meta.json）但含未提交改动，拒绝自动清理（防丢代码）。\n` +
@@ -358,15 +372,15 @@ export class WorktreeManager {
         try { rmSync(worktreePath, { recursive: true, force: true }); } catch {}
         // 同步清理 git worktree 注册 + 残留分支，否则目录虽删但 git 内部状态未清，
         // 后续 git worktree add 会因「worktree 已注册」或「分支已存在」失败
-        try { gitQuiet(this.cwd, 'worktree prune'); } catch {}
-        try { gitQuiet(this.cwd, `branch -D ${branch}`); } catch {}
+        try { gitQuiet(this.cwd, ['worktree', 'prune'], { timeout: 30000 }); } catch {}
+        try { gitQuiet(this.cwd, ['branch', '-D', branch]); } catch {}
       } else {
         throw new Error(`worktree already exists: ${name}. Run cleanup first.`);
       }
     }
 
     // 2. 检查分支是否已存在
-    if (gitQuiet(this.cwd, `rev-parse --verify refs/heads/${branch}`)) {
+    if (gitQuiet(this.cwd, ['rev-parse', '--verify', `refs/heads/${branch}`])) {
       throw new Error(`branch already exists: ${branch}. Run cleanup first.`);
     }
 
@@ -374,11 +388,11 @@ export class WorktreeManager {
     let baseBranch = base;
     let baseHash;
     if (baseBranch) {
-      baseHash = git(this.cwd, `rev-parse ${baseBranch}`);
+      baseHash = git(this.cwd, ['rev-parse', baseBranch]);
     } else {
       // 默认用当前 HEAD
-      baseBranch = gitQuiet(this.cwd, `symbolic-ref --short HEAD`) || git(this.cwd, `rev-parse HEAD`);
-      baseHash = git(this.cwd, `rev-parse HEAD`);
+      baseBranch = gitQuiet(this.cwd, ['symbolic-ref', '--short', 'HEAD']) || git(this.cwd, ['rev-parse', 'HEAD']);
+      baseHash = git(this.cwd, ['rev-parse', 'HEAD']);
     }
 
     // 4. 创建 worktree 根目录
@@ -391,12 +405,12 @@ export class WorktreeManager {
     // 未切分支，直接写代码污染 main（见缺陷 execute-in-place-windows-pitfalls 坑1）。
     // core.longpaths=true 让 git 用 \\?\ 前缀绕过 MAX_PATH，幂等、Windows 推荐、低风险，失败不阻断。
     if (process.platform === 'win32') {
-      try { gitQuiet(this.cwd, 'config core.longpaths true'); } catch {}
+      try { gitQuiet(this.cwd, ['config', 'core.longpaths', 'true']); } catch {}
     }
 
     // 5. 创建 worktree（含版本检测 + sandbox fallback）
     try {
-      git(this.cwd, `worktree add ${worktreePath} -b ${branch} ${baseHash}`);
+      git(this.cwd, ['worktree', 'add', worktreePath, '-b', branch, baseHash], { timeout: 120000 });
     } catch (e) {
       const check = isGitWorktreeSupported(this.cwd);
       if (!check.supported) {
@@ -471,7 +485,7 @@ export class WorktreeManager {
       branch,
       baseBranch,
       baseHash,
-      actualBaseHash: gitQuiet(worktreePath, 'rev-parse HEAD') || baseHash,
+      actualBaseHash: gitQuiet(worktreePath, ['rev-parse', 'HEAD']) || baseHash,
       createdAt: new Date().toISOString(),
       worktreePath,
       mode: 'worktree',
@@ -499,7 +513,7 @@ export class WorktreeManager {
    * @private
    */
   _recoverNativeWorktreeMeta(name, { worktreePath, branch }) {
-    const baseHash = gitQuiet(worktreePath, 'rev-parse HEAD') || null
+    const baseHash = gitQuiet(worktreePath, ['rev-parse', 'HEAD']) || null
     const meta = {
       name_zh: 'worktree 元数据',
       changeName: name,
@@ -552,15 +566,15 @@ export class WorktreeManager {
     if (resolvedSource === resolvedTarget) {
       console.warn('⚠️  跳过 baseline overlay：当前目录与目标目录相同（native-worktree 或 in-place 模式）')
       // 写 meta 但不 overlay
-      baseBranch = baseBranch || gitQuiet(this.cwd, 'symbolic-ref --short HEAD') || gitQuiet(this.cwd, 'rev-parse HEAD')
-      baseHash = baseHash || git(this.cwd, 'rev-parse HEAD')
+      baseBranch = baseBranch || gitQuiet(this.cwd, ['symbolic-ref', '--short', 'HEAD']) || gitQuiet(this.cwd, ['rev-parse', 'HEAD'])
+      baseHash = baseHash || git(this.cwd, ['rev-parse', 'HEAD'])
       const meta = {
         name_zh: 'worktree 元数据',
       changeName: name,
         branch: branch || BRANCH_PREFIX + name,
         baseBranch,
         baseHash,
-        actualBaseHash: gitQuiet(worktreePath, 'rev-parse HEAD') || baseHash,
+        actualBaseHash: gitQuiet(worktreePath, ['rev-parse', 'HEAD']) || baseHash,
         createdAt: new Date().toISOString(),
         worktreePath,
         mode: mode || 'in-place-fallback',
@@ -578,8 +592,8 @@ export class WorktreeManager {
 
     // 解析 base
     if (!baseHash) {
-      baseBranch = baseBranch || gitQuiet(this.cwd, 'symbolic-ref --short HEAD') || gitQuiet(this.cwd, 'rev-parse HEAD');
-      baseHash = git(this.cwd, 'rev-parse HEAD');
+      baseBranch = baseBranch || gitQuiet(this.cwd, ['symbolic-ref', '--short', 'HEAD']) || gitQuiet(this.cwd, ['rev-parse', 'HEAD']);
+      baseHash = git(this.cwd, ['rev-parse', 'HEAD']);
     }
 
     const baselineResult = this._overlayBaseline(this.cwd, this.cwd);
@@ -597,7 +611,7 @@ export class WorktreeManager {
       branch: branch || BRANCH_PREFIX + name,
       baseBranch,
       baseHash,
-      actualBaseHash: gitQuiet(worktreePath, 'rev-parse HEAD') || baseHash,
+      actualBaseHash: gitQuiet(worktreePath, ['rev-parse', 'HEAD']) || baseHash,
       createdAt: new Date().toISOString(),
       worktreePath,
       mode: mode || 'in-place-fallback',
@@ -622,7 +636,7 @@ export class WorktreeManager {
   }
 
   /**
-   * 构建 isolation 信息对象，用于写入 gate-status.json
+   * 构建 isolation 信息对象，用于写入 sillyspec.db（_writeIsolationToDB，isolation_status 列）
    * @param {string} changeName
    * @returns {{ status: string, mode: string, path: string } | null}
    */
@@ -724,8 +738,14 @@ export class WorktreeManager {
     if (!isInPlace && existsSync(worktreePath)) {
       const wtNodeModules = join(worktreePath, 'node_modules');
       if (existsSync(wtNodeModules)) {
-        let isLink = false;
-        try { isLink = lstatSync(wtNodeModules).isSymbolicLink(); } catch {}
+        // lstat 失败 fail-loud（D-001@v1 / review-2026-08-09 #4）：EPERM（杀毒/索引锁 junction）若静默跳过解链，
+        // 后续 git worktree remove / rmSync recursive 会跟随 junction 误删主仓 node_modules
+        let isLink;
+        try {
+          isLink = lstatSync(wtNodeModules).isSymbolicLink();
+        } catch (e) {
+          throw new Error(`worktree node_modules junction 检测失败（疑似 EPERM：杀毒/索引占用），阻断 cleanup 保护主仓 node_modules：${e.message}。请关闭占用进程或手动 rmdir "${wtNodeModules}" 后重试 sillyspec worktree cleanup`);
+        }
         if (isLink) {
           try {
             if (process.platform === 'win32') {
@@ -736,7 +756,7 @@ export class WorktreeManager {
             }
             details.push('worktree node_modules junction/symlink removed (protect main checkout)');
           } catch (e) {
-            details.push(`node_modules link remove failed: ${e.message}`);
+            throw new Error(`worktree node_modules junction 解链失败，阻断 cleanup 保护主仓 node_modules：${e.message}。请手动 rmdir "${wtNodeModules}" 后重试`);
           }
         }
       }
@@ -747,7 +767,7 @@ export class WorktreeManager {
     if (!isInPlace && existsSync(worktreePath)) {
       for (let attempt = 1; attempt <= maxRetries; attempt++) {
         try {
-          git(this.cwd, `worktree remove ${worktreePath} --force`);
+          git(this.cwd, ['worktree', 'remove', worktreePath, '--force'], { timeout: 60000 });
           gitRemoveOk = true;
           details.push(`git worktree remove succeeded (attempt ${attempt})`);
           break;
@@ -773,14 +793,14 @@ export class WorktreeManager {
 
     // 3. git worktree prune（清理 git 内部注册信息）
     try {
-      gitQuiet(this.cwd, 'worktree prune');
+      gitQuiet(this.cwd, ['worktree', 'prune'], { timeout: 30000 });
     } catch {
       // prune 失败不阻断
     }
 
     // 4. 删除分支（忽略分支不存在的错误）
     try {
-      gitQuiet(this.cwd, `branch -D ${branch}`);
+      gitQuiet(this.cwd, ['branch', '-D', branch]);
       details.push('branch deleted');
     } catch {
       // 分支可能已被删除，幂等跳过
@@ -800,7 +820,7 @@ 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`)?.includes(worktreePath)) {
+    if (!isInPlace && gitQuiet(this.cwd, ['worktree', 'list'], { timeout: 30000 })?.includes(worktreePath)) {
       residual.push('git worktree list still references this worktree');
     }
     if (residual.length > 0) {
@@ -832,19 +852,79 @@ export class WorktreeManager {
    * @param {{ fix?: boolean, staleHours?: number }} opts
    * @returns {{ issues: Array<{ type: string, name: string, detail: string, fixable: boolean }>, fixed: string[], unfixable: string[] }}
    */
+  /**
+   * doctor --fix 的依赖重供给：先解 worktree/node_modules junction（保护主仓 node_modules），
+   * 再 provisionDeps(force:true) 强制走 install 分支重装。
+   *
+   * Windows 保护（与 cleanup 722-743 同源坑）：不解链直接 install 会经 junction 误改主仓
+   * node_modules 内容。in-place-fallback 无独立 node_modules（worktreePath 即主仓），跳过解链，
+   * 仅 install。force=true 绕过 provisionDeps 的 lockfile 一致快路径，确保真重装而非幂等 linked。
+   *
+   * @param {string} name - changeName
+   * @param {string} wtPath - worktree 根目录（meta.worktreePath）
+   * @returns {{ ok: boolean, msg: string }}
+   */
   _doctorReprovision(name, wtPath) {
     try {
-      const deps = provisionDeps(wtPath, this.cwd, { specBase: join(this.cwd, '.sillyspec') }) || {};
-      const metaPath = join(this.getWorktreePath(name), META_FILE);
       const meta = this.getMeta(name) || {};
-      writeMetaAtomic(metaPath, { ...meta, ...deps });
+      const isInPlace = meta.mode === 'in-place-fallback';
+      // 先解 junction（非 in-place）：lstatSync 判 link → Windows rmdir junction / Unix unlinkSync
+      if (!isInPlace && existsSync(wtPath)) {
+        const wtNodeModules = join(wtPath, 'node_modules');
+        if (existsSync(wtNodeModules)) {
+          // lstat 失败 fail-loud（D-001@v1）+ 解链失败 fail-loud（D-002@v1 / review-2026-08-09 #4）：
+          // 原 best-effort「交 provisionDeps install」会经 junction 误改主仓 node_modules，正是 #4 坑
+          let isLink;
+          try {
+            isLink = lstatSync(wtNodeModules).isSymbolicLink();
+          } catch (e) {
+            throw new Error(`worktree node_modules junction 检测失败（疑似 EPERM：杀毒/索引占用），阻断 doctor reprovision 保护主仓 node_modules：${e.message}。请关闭占用进程或手动 rmdir "${wtNodeModules}" 后重试`);
+          }
+          if (isLink) {
+            try {
+              if (process.platform === 'win32') {
+                execSync(`rmdir "${wtNodeModules}"`, { shell: 'cmd.exe' });
+              } else {
+                unlinkSync(wtNodeModules);
+              }
+            } catch (e) {
+              throw new Error(`worktree node_modules junction 解链失败，阻断 doctor reprovision（不调 provisionDeps 避免经 junction 误改主仓）：${e.message}。请手动 rmdir "${wtNodeModules}" 后重试`);
+            }
+          }
+        }
+      }
+      const deps = provisionDeps(wtPath, this.cwd, {
+        specBase: join(this.cwd, '.sillyspec'),
+        force: true,
+      }) || {};
+      const metaPath = join(this.getWorktreePath(name), META_FILE);
+      // 成功重供时清掉旧 depsError（provisionDeps 成功结果不含该键，{...meta,...deps} 会残留旧值）
+      const merged = { ...meta, ...deps };
+      if (deps.depsStatus !== 'failed') delete merged.depsError;
+      writeMetaAtomic(metaPath, merged);
       return { ok: true, msg: `re-provisioned ${name}: depsStatus=${deps.depsStatus}` };
     } catch (e) {
       return { ok: false, msg: `re-provision failed for ${name}: ${e.message}` };
     }
   }
 
-  doctor({ fix = false, staleHours = 24 } = {}) {
+  /**
+   * worktree 健康检查 + 可选修复
+   * 检查项：
+   * - git worktree list 中的孤儿条目（目录不存在）
+   * - worktree 目录存在但 git 不认识
+   * - meta 存在但 worktree 目录不存在
+   * - worktree 目录存在但 meta 不存在（幽灵目录）
+   * - SillySpec 分支残留（sillyspec/* 但无对应 meta）
+   * - 超过指定小时的过期 worktree
+   * - deps 依赖状态（failed/missing/stale/main-drift，复用 checkDepsFreshness 统一判定）
+   *
+   * @param {{ fix?: boolean, staleHours?: number, changeName?: string|null }} opts
+   *   - changeName：非 null 时仅扫描该 change（deps/ghost/stale/orphan-git/orphan-branch 全部按 changeName 过滤）；
+   *     不传则全量扫（兼容现有行为）。
+   * @returns {{ issues: Array<{ type: string, name: string, detail: string, fixable: boolean }>, fixed: string[], unfixable: string[] }}
+   */
+  doctor({ fix = false, staleHours = 24, changeName = null } = {}) {
     const issues = [];
     const fixed = [];
     const unfixable = [];
@@ -852,7 +932,7 @@ export class WorktreeManager {
     // 1. 列出 git worktree list 中的条目
     let gitWorktreeList = [];
     try {
-      const raw = execSync(`git worktree list --porcelain`, { cwd: this.cwd, encoding: 'utf8', stdio: ['pipe','pipe','pipe'] });
+      const raw = git(this.cwd, ['worktree', 'list', '--porcelain'], { timeout: 30000 });
       const entries = raw.split(/\n\n/).filter(Boolean);
       for (const entry of entries) {
         const lines = entry.split('\n');
@@ -880,11 +960,12 @@ export class WorktreeManager {
     for (const wt of gitWorktreeList) {
       if (!existsSync(wt.path)) {
         const name = this._pathToChangeName(wt.path);
+        if (changeName && name !== changeName) continue; // --change 过滤：仅扫指定 change
         if (wt.missing === true) {
           // git 明确标记目录缺失（git 2.20+）→ 真 orphan，prune 安全
           issues.push({ type: 'orphan-git-entry', name: name || wt.path, detail: `git worktree 标记 missing: ${wt.path}`, fixable: true });
           if (fix) {
-            try { gitQuiet(this.cwd, 'worktree prune'); fixed.push(`pruned orphan: ${wt.path}`); } catch { unfixable.push(`prune failed for: ${wt.path}`); }
+            try { gitQuiet(this.cwd, ['worktree', 'prune'], { timeout: 30000 }); fixed.push(`pruned orphan: ${wt.path}`); } catch { unfixable.push(`prune failed for: ${wt.path}`); }
           }
         } else {
           // 目录不可见但 git 未标记 missing → 可能 existsSync 误判，保守不自动 prune
@@ -901,25 +982,28 @@ export class WorktreeManager {
       for (const entry of entries) {
         if (!entry.isDirectory()) continue;
         const name = entry.name;
+        if (changeName && name !== changeName) continue; // --change 过滤：仅扫指定 change
         const dirPath = join(this.worktreeBase, name);
         const hasMeta = existsSync(join(dirPath, META_FILE));
         const meta = hasMeta ? this.getMeta(name) : null;
 
-        // deps 依赖状态检查（change 2026-06-28-worktree-deps-provision）
-        if (meta && meta.worktreePath && existsSync(meta.worktreePath) && meta.mode !== 'in-place-fallback') {
+        // deps 依赖状态检查（change 2026-06-28-worktree-deps-provision / 2026-08-05-tooling-feedback-fixes）
+        // 复用 checkDepsFreshness（H1，worktree-deps.js），优先级 failed→missing→stale→main-drift→fresh。
+        // 放宽原 909 in-place-fallback 守卫：in-place 也跑（main-drift/stale/failed 对它同样有意义，
+        // 真 in-place 的 wtPath===主仓→wtHash===mainHash→不会误报 main-drift，仅 failed/stale 有意义）。
+        // fix 时 _doctorReprovision 自行判断是否解链（in-place 不解链，仅 install）。
+        if (meta && meta.worktreePath && existsSync(meta.worktreePath)) {
           const wtPath = meta.worktreePath;
-          const nmExists = existsSync(join(wtPath, 'node_modules'));
-          const curHash = lockfileHash(wtPath);
-          let depsIssue = null;
-          if (['linked', 'installed'].includes(meta.depsStatus) && !nmExists) {
-            depsIssue = { type: 'deps-missing', detail: 'meta.depsStatus=' + meta.depsStatus + ' 但 node_modules 缺失' };
-          } else if (meta.depsLockHash && curHash && curHash !== meta.depsLockHash) {
-            depsIssue = { type: 'deps-stale', detail: 'lockfile 变化 (' + meta.depsLockHash + ' -> ' + curHash + ')' };
-          } else if (meta.depsStatus === 'failed') {
-            depsIssue = { type: 'deps-failed', detail: '上次依赖供给失败' + (meta.depsError ? ': ' + meta.depsError : '') };
-          }
-          if (depsIssue) {
-            issues.push({ type: depsIssue.type, name, detail: depsIssue.detail, fixable: true });
+          const fresh = checkDepsFreshness(meta, wtPath, this.cwd);
+          const issueTypeByStatus = {
+            failed: 'deps-failed',
+            missing: 'deps-missing',
+            stale: 'deps-stale',
+            'main-drift': 'deps-main-drift',
+          };
+          const issueType = issueTypeByStatus[fresh.status] || null;
+          if (issueType) {
+            issues.push({ type: issueType, name, detail: fresh.detail, fixable: true });
             if (fix) {
               const r = this._doctorReprovision(name, wtPath);
               (r.ok ? fixed : unfixable).push(r.msg);
@@ -973,15 +1057,16 @@ export class WorktreeManager {
 
     // 5. 检查 SillySpec 分支残留
     try {
-      const branches = execSync(`git branch --list '${BRANCH_PREFIX}*'`, { cwd: this.cwd, encoding: 'utf8', stdio: ['pipe','pipe','pipe'] }).trim();
+      const branches = execFileSync('git', ['branch', '--list', `${BRANCH_PREFIX}*`], { cwd: this.cwd, encoding: 'utf8', stdio: ['pipe','pipe','pipe'] }).trim();
       if (branches) {
         for (const line of branches.split('\n').filter(Boolean)) {
           const branch = line.replace(/^\*?\s+/, '').trim();
           const name = branch.replace(BRANCH_PREFIX, '');
+          if (changeName && name !== changeName) continue; // --change 过滤：仅扫指定 change
           if (!metaNames.has(name)) {
             issues.push({ type: 'orphan-branch', name, detail: `分支残留（无对应 meta）: ${branch}`, fixable: true });
             if (fix) {
-              try { gitQuiet(this.cwd, `branch -D ${branch}`); fixed.push(`deleted orphan branch: ${branch}`); } catch { unfixable.push(`branch delete failed: ${branch}`); }
+              try { gitQuiet(this.cwd, ['branch', '-D', branch]); fixed.push(`deleted orphan branch: ${branch}`); } catch { unfixable.push(`branch delete failed: ${branch}`); }
             }
           }
         }
@@ -1028,9 +1113,9 @@ export class WorktreeManager {
     const isDeliverable = f => f && !f.startsWith('.sillyspec/') && f !== 'meta.json';
     try {
       // 1) 候选交付变更（worktree 工作区相对 diffBase）。--no-renames：rename 退化成 D+A，两侧文件都进集
-      const tracked = (gitQuiet(worktreePath, `diff --no-renames --name-only ${diffBase}`) || '')
+      const tracked = (gitQuiet(worktreePath, ['diff', '--no-renames', '--name-only', diffBase], { timeout: 30000 }) || '')
         .split('\n').filter(Boolean).filter(isDeliverable);
-      const untracked = (gitQuiet(worktreePath, `ls-files --others --exclude-standard`) || '')
+      const untracked = (gitQuiet(worktreePath, ['ls-files', '--others', '--exclude-standard'], { timeout: 30000 }) || '')
         .split('\n').filter(Boolean).filter(isDeliverable);
 
       if (tracked.length === 0 && untracked.length === 0) {
@@ -1063,19 +1148,19 @@ export class WorktreeManager {
    * @returns {string[]} 尚未落到 main HEAD 的文件
    */
   _changesAlreadyOnMain(worktreePath, trackedFiles, untrackedFiles) {
-    const mainHead = git(this.cwd, 'rev-parse HEAD'); // 失败即抛 → 外层 catch fail-safe
+    const mainHead = git(this.cwd, ['rev-parse', 'HEAD']); // 失败即抛 → 外层 catch fail-safe
     const pending = [];
 
     if (trackedFiles.length > 0) {
       const diverged = (gitQuiet(worktreePath,
-        `diff --no-renames --name-only ${mainHead} -- ${trackedFiles.join(' ')}`) || '')
+        ['diff', '--no-renames', '--name-only', mainHead, '--', ...trackedFiles], { timeout: 30000 }) || '')
         .split('\n').filter(Boolean);
       pending.push(...diverged);
     }
 
     if (untrackedFiles.length > 0) {
       // hash-object 按 argv 顺序逐行输出 blob hash；某文件不存在则整命令失败 → gitQuiet 返回 null
-      const wtHashes = (gitQuiet(worktreePath, `hash-object -- ${untrackedFiles.join(' ')}`) || '')
+      const wtHashes = (gitQuiet(worktreePath, ['hash-object', '--', ...untrackedFiles], { timeout: 30000 }) || '')
         .split('\n');
       const mainBlobs = this._lsTreeBlobs(this.cwd, 'HEAD', untrackedFiles);
       for (let i = 0; i < untrackedFiles.length; i++) {
@@ -1101,7 +1186,7 @@ export class WorktreeManager {
   _lsTreeBlobs(cwd, treeish, files) {
     const map = new Map();
     if (!files || files.length === 0) return map; // 空 pathspec 会列整棵树，必须拦
-    const raw = gitQuiet(cwd, `ls-tree ${treeish} -- ${files.join(' ')}`);
+    const raw = gitQuiet(cwd, ['ls-tree', treeish, '--', ...files]);
     if (!raw) return map;
     for (const line of raw.split('\n')) {
       if (!line) continue;
@@ -1121,8 +1206,13 @@ export class WorktreeManager {
     try {
       const resolved = resolve(wtPath);
       const baseResolved = resolve(this.worktreeBase);
-      if (resolved.startsWith(baseResolved + '/')) {
-        return resolved.slice(baseResolved.length + 1);
+      // 用 path.relative 比 startsWith(base + sep) 更稳：
+      // - 自动用当前平台分隔符比较（Windows 上 resolve 返回反斜杠，硬编码 '/' 恒 false）
+      // - 跨盘符（C: vs D:）时返回绝对路径 → isAbsolute 守卫放行失败兜底 null
+      // - 同路径返回 '' → 视作非 changeName
+      const rel = relative(baseResolved, resolved);
+      if (rel && !rel.startsWith('..') && !isAbsolute(rel)) {
+        return rel;
       }
     } catch {}
     return null;
@@ -1142,16 +1232,21 @@ export class WorktreeManager {
 
     try {
       // staged 变更
-      const staged = gitQuiet(mainCwd, 'diff --cached --name-only') || '';
+      const staged = gitQuiet(mainCwd, ['diff', '--cached', '--name-only'], { timeout: 30000 }) || '';
       if (staged) {
         try {
           // 用 Buffer 模式读取，避免二进制 patch 被 UTF-8 解码损坏
-          const patchBuf = execSync(`git diff --cached --binary`, { cwd: mainCwd, stdio: ['pipe','pipe','pipe'] });
+          const patchBuf = execFileSync('git', ['diff', '--cached', '--binary'], { cwd: mainCwd, stdio: ['pipe','pipe','pipe'] });
           if (patchBuf && patchBuf.length > 0) {
             const patchFile = join(worktreePath, '.sillyspec-baseline-staged.patch');
-            writeFileSync(patchFile, patchBuf);
-            git(worktreePath, `apply --binary ${patchFile}`);
-            rmSync(patchFile, { force: true });
+            try {
+              writeFileSync(patchFile, patchBuf);
+              git(worktreePath, ['apply', '--binary', patchFile], { timeout: 30000 });
+            } finally {
+              // git apply 抛错时也要清掉 patch 临时文件，避免泄漏到 worktree/主仓根
+              // （filterDeliverableFiles 不排除 .sillyspec-baseline-*，泄漏会级联 BLOCKED 下游 apply）
+              try { rmSync(patchFile, { force: true }); } catch {}
+            }
           }
         } catch (e) {
           errors.push(`staged: ${e.message}`);
@@ -1160,16 +1255,20 @@ export class WorktreeManager {
       }
 
       // unstaged 变更
-      const unstaged = gitQuiet(mainCwd, 'diff --name-only') || '';
+      const unstaged = gitQuiet(mainCwd, ['diff', '--name-only'], { timeout: 30000 }) || '';
       if (unstaged) {
         try {
           // 用 Buffer 模式读取，避免二进制 patch 被 UTF-8 解码损坏
-          const patchBuf = execSync(`git diff --binary`, { cwd: mainCwd, stdio: ['pipe','pipe','pipe'] });
+          const patchBuf = execFileSync('git', ['diff', '--binary'], { cwd: mainCwd, stdio: ['pipe','pipe','pipe'] });
           if (patchBuf && patchBuf.length > 0) {
             const patchFile = join(worktreePath, '.sillyspec-baseline-unstaged.patch');
-            writeFileSync(patchFile, patchBuf);
-            git(worktreePath, `apply --binary ${patchFile}`);
-            rmSync(patchFile, { force: true });
+            try {
+              writeFileSync(patchFile, patchBuf);
+              git(worktreePath, ['apply', '--binary', patchFile], { timeout: 30000 });
+            } finally {
+              // git apply 抛错时也要清掉 patch 临时文件，避免泄漏到 worktree/主仓根
+              try { rmSync(patchFile, { force: true }); } catch {}
+            }
           }
         } catch (e) {
           errors.push(`unstaged: ${e.message}`);
@@ -1177,18 +1276,20 @@ export class WorktreeManager {
         files.push(...unstaged.split('\n').filter(Boolean));
       }
 
-      // untracked 文件（排除 .sillyspec/.runtime 等）
-      const untracked = gitQuiet(mainCwd, 'ls-files --others --exclude-standard') || '';
+      // untracked 文件（排除 .sillyspec/.runtime 等）；目录跳过避免 readFileSync EISDIR
+      const untracked = gitQuiet(mainCwd, ['ls-files', '--others', '--exclude-standard'], { timeout: 30000 }) || '';
+      const skippedDirs = [];
       if (untracked) {
         for (const f of untracked.split('\n').filter(Boolean)) {
-          const src = join(mainCwd, f);
-          const dst = join(worktreePath, f);
-          if (existsSync(src)) {
-            mkdirSync(dirname(dst), { recursive: true });
-            try { writeFileSync(dst, readFileSync(src)); files.push(f); } catch (e) { errors.push(`untracked ${f}: ${e.message}`); }
-          }
+          const r = copyUntrackedEntry(join(mainCwd, f), join(worktreePath, f));
+          if (r.status === 'copied') files.push(f);
+          else if (r.status === 'skipped-dir') skippedDirs.push(f);
+          else if (r.status === 'error') errors.push(`untracked ${f}: ${r.error}`);
         }
       }
+      if (skippedDirs.length > 0) {
+        console.log(`ℹ️  baseline overlay 跳过 ${skippedDirs.length} 个 untracked 目录（不读目录避免 EISDIR，坑 execute-worktree-overlay-untracked-dir-eisdir）`);
+      }
 
       if (files.length > 0) {
         console.log(`📁 baseline overlay: ${files.length} 个未提交文件已同步到 worktree`);
@@ -1234,21 +1335,22 @@ export class WorktreeManager {
       GIT_COMMITTER_EMAIL: 'sillyspec@baseline',
     };
     try {
-      execSync('git add -A', { cwd: worktreePath, encoding: 'utf8', stdio: ['pipe','pipe','pipe'], env });
+      git(worktreePath, ['add', '-A'], { timeout: 30000 });
       // 检查是否有实际变更（可能 overlay 后和 HEAD 完全一致）
-      const status = gitQuiet(worktreePath, 'status --porcelain');
+      const status = gitQuiet(worktreePath, ['status', '--porcelain'], { timeout: 30000 });
       if (!status) {
-        return gitQuiet(worktreePath, 'rev-parse HEAD');
+        return gitQuiet(worktreePath, ['rev-parse', 'HEAD']);
       }
       // --no-verify：baseline 是锚点不是交付物，只是把主仓库 dirty 文件快照到 worktree
       // 分支上以便区分「前置 baseline」与「子代理新增改动」。它不该触发项目 pre-commit
       // hook（如 ruff format），否则主仓库 dirty 文件中任一不达标的会被 hook reformat
       // 致 commit 失败 → worktree 创建失败 → execute 无法启动。
-      execSync(
-        `git commit --no-verify -m "sillyspec: baseline checkpoint for ${changeName}"`,
+      execFileSync(
+        'git',
+        ['commit', '--no-verify', '-m', `sillyspec: baseline checkpoint for ${changeName}`],
         { cwd: worktreePath, encoding: 'utf8', stdio: ['pipe','pipe','pipe'], env }
       );
-      const hash = git(worktreePath, 'rev-parse HEAD');
+      const hash = git(worktreePath, ['rev-parse', 'HEAD']);
       console.log(`📌 baseline checkpoint: ${hash}`);
       return hash;
     } catch (e) {