@ifrankwang/openspec-agents 0.130.0 → 0.131.0

package/.mcp-server/cli.mjs

@@ -29686,6 +29686,7 @@ var EMPTY_COMPLETION_RESULT = {
 
 // src/core/tools/lifecycle.ts
 import path6 from "path";
+import { rmdir } from "node:fs/promises";
 
 // src/core/types.ts
 var CODE_DIMENSIONS = ["style", "architecture", "performance", "security", "maintainability"];
@@ -29742,7 +29743,15 @@ function reviewLayerFromMetadata(child) {
 // src/core/git.ts
 import path from "path";
 import { execFile } from "node:child_process";
-import { readFile, writeFile, stat } from "node:fs/promises";
+import { readFile, writeFile, stat, rm } from "node:fs/promises";
+async function pathExists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
 function execGit(args) {
   return new Promise((resolve) => {
     const child = execFile("git", args, { encoding: "utf-8", maxBuffer: 10 * 1024 * 1024 }, (err, stdout, stderr) => {
@@ -29775,6 +29784,55 @@ async function runGit(worktree, args) {
 async function runGitChecked(worktree, args) {
   return gitRunner.runChecked(worktree, args);
 }
+async function removeTaskGroupWorktree(repoRoot, wtPath, opts = {}) {
+  const result = { dirResolved: false, dirResolvedByFallback: false, pruned: false, branchDeleted: null, errors: [] };
+  if (!await pathExists(wtPath)) {
+    const pruneRes = await runGitChecked(repoRoot, ["worktree", "prune"]);
+    if (pruneRes.success)
+      result.pruned = true;
+    else
+      result.errors.push(`worktree prune 失败：${pruneRes.stderr}`);
+    result.dirResolved = true;
+  } else {
+    const rmRes = await runGitChecked(repoRoot, ["worktree", "remove", wtPath, "--force"]);
+    if (!rmRes.success)
+      result.errors.push(`git worktree remove 失败：${rmRes.stderr}`);
+    if (await pathExists(wtPath)) {
+      try {
+        await rm(wtPath, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+      } catch (e) {
+        result.errors.push(`文件系统兜底删除 "${wtPath}" 失败：${e instanceof Error ? e.message : String(e)}`);
+      }
+      const pruneRes = await runGitChecked(repoRoot, ["worktree", "prune"]);
+      if (pruneRes.success)
+        result.pruned = true;
+      else
+        result.errors.push(`worktree prune 失败：${pruneRes.stderr}`);
+      if (!await pathExists(wtPath)) {
+        result.dirResolved = true;
+        result.dirResolvedByFallback = true;
+      }
+    } else {
+      result.dirResolved = true;
+    }
+  }
+  if (!result.dirResolved) {
+    if (opts.branchName) {
+      result.errors.push(`目录 "${wtPath}" 未能删除，跳过分支 "${opts.branchName}" 的删除以保留排查线索`);
+    }
+    return result;
+  }
+  if (opts.branchName) {
+    const branchRes = await runGitChecked(repoRoot, ["branch", "-D", opts.branchName]);
+    if (branchRes.success)
+      result.branchDeleted = true;
+    else {
+      result.branchDeleted = false;
+      result.errors.push(`删除分支 "${opts.branchName}" 失败：${branchRes.stderr}`);
+    }
+  }
+  return result;
+}
 async function getCurrentHead(worktree) {
   return runGit(worktree, ["rev-parse", "HEAD"]);
 }
@@ -32695,16 +32753,21 @@ function requireLoader() {
       state.result += _result;
     }
   }
+  function chargeMergeWork(state) {
+    state.totalMergeKeys++;
+    if (state.maxTotalMergeKeys !== -1 && state.totalMergeKeys > state.maxTotalMergeKeys) {
+      throwError(state, "merge keys exceeded maxTotalMergeKeys (" + state.maxTotalMergeKeys + ")");
+    }
+  }
   function mergeMappings(state, destination, source, overridableKeys) {
     if (!common2.isObject(source)) {
       throwError(state, "cannot merge mappings; the provided source object is unacceptable");
     }
+    chargeMergeWork(state);
     const sourceKeys = Object.keys(source);
     for (let index = 0, quantity = sourceKeys.length;index < quantity; index += 1) {
       const key = sourceKeys[index];
-      if (state.maxTotalMergeKeys !== -1 && ++state.totalMergeKeys > state.maxTotalMergeKeys) {
-        throwError(state, "merge keys exceeded maxTotalMergeKeys (" + state.maxTotalMergeKeys + ")");
-      }
+      chargeMergeWork(state);
       if (!_hasOwnProperty.call(destination, key)) {
         setProperty(destination, key, source[key]);
         overridableKeys[key] = true;
@@ -32732,6 +32795,9 @@ function requireLoader() {
     }
     if (keyTag === "tag:yaml.org,2002:merge") {
       if (Array.isArray(valueNode)) {
+        if (valueNode.length > 100) {
+          throwError(state, "abnormal merge sequence size");
+        }
         for (let index = 0, quantity = valueNode.length;index < quantity; index += 1) {
           mergeMappings(state, _result, valueNode[index], overridableKeys);
         }
@@ -36329,13 +36395,15 @@ async function setWorktreeExecute(params, ctx) {
         await bindWorktreeRefs(item, existingPath, branch, state.baseBranch);
         reused = true;
       } else {
-        const rmResult = await runGitChecked(repoRoot, ["worktree", "remove", existingPath, "--force"]);
-        if (!rmResult.success) {
-          throw new Error(`无法清理已有 worktree "${existingPath}"：${rmResult.stderr}`);
-        }
-        const branchRmResult = await runGitChecked(repoRoot, ["branch", "-D", branch]);
-        if (!branchRmResult.success) {
-          throw new Error(`无法清理已有分支 "${branch}"：${branchRmResult.stderr}`);
+        const cleanup = await removeTaskGroupWorktree(repoRoot, existingPath, { branchName: branch });
+        if (!cleanup.dirResolved || cleanup.branchDeleted === false) {
+          const problems = [];
+          if (!cleanup.dirResolved)
+            problems.push(`无法清理已有 worktree "${existingPath}"`);
+          if (cleanup.branchDeleted === false)
+            problems.push(`无法清理已有分支 "${branch}"`);
+          throw new Error(`${problems.join("；")}：${cleanup.errors.join("；") || "原因未知"}
+请手动处理后重试。`);
         }
       }
     }
@@ -36399,6 +36467,19 @@ async function statusExecute(params, ctx) {
   const exemptionItems = (await readExemptions(ctx.worktree)).items;
   return renderWorkflowStatusView(item, workflow, rec, { agent, orchestrator: ctx.orchestrator, identityDeclared: ctx.identityDeclared }, { state, tg, mainPollution, toolChanges, exemptedHits, exemptionItems });
 }
+async function sweepEmptyWorktreeParents(repoRoot, removedDir, changeId) {
+  const repoRootAbs = path6.resolve(repoRoot);
+  const groupLevelDir = path6.join(repoRootAbs, ".worktree", changeId);
+  const worktreeLevelDir = path6.join(repoRootAbs, ".worktree");
+  if (path6.dirname(path6.resolve(removedDir)) === groupLevelDir) {
+    try {
+      await rmdir(groupLevelDir);
+    } catch {}
+  }
+  try {
+    await rmdir(worktreeLevelDir);
+  } catch {}
+}
 async function completeTaskGroupExecute(params, ctx) {
   assertOrchestrator(ctx, "opx_orch_complete_task_group");
   const state = await readStateByWorktree(ctx.worktree, params.change_id);
@@ -36453,17 +36534,42 @@ async function completeTaskGroupExecute(params, ctx) {
 `);
     }
   }
-  if (worktreePath && branchName) {
-    try {
-      await runGit(ctx.worktree, ["worktree", "remove", worktreePath, "--force"]);
-      await runGit(ctx.worktree, ["branch", "-D", branchName]);
-    } catch {}
+  let cleanupNote = "";
+  let cleanupResidualWarning = "";
+  if (worktreePath) {
+    const cleanup = await removeTaskGroupWorktree(ctx.worktree, worktreePath, { branchName });
+    if (cleanup.dirResolved) {
+      await sweepEmptyWorktreeParents(ctx.worktree, worktreePath, params.change_id);
+      const successNotes = [];
+      if (cleanup.dirResolvedByFallback) {
+        successNotes.push("- **cleanup**: git worktree remove 未直接移除目录，已按文件系统兜底删除并 prune 管理记录。");
+      }
+      if (cleanup.errors.length > 0) {
+        successNotes.push(`- **cleanup 部分告警**: ${cleanup.errors.join("；")}`);
+      }
+      cleanupNote = successNotes.join(`
+`);
+    } else {
+      item.metadata["cleanup_residual"] = { worktree_path: worktreePath, errors: cleanup.errors };
+      cleanupResidualWarning = [
+        "",
+        "## ⚠️ worktree 清理残留（不影响收尾）",
+        `- **残留路径**: \`${worktreePath}\``,
+        "- **原因**:",
+        ...cleanup.errors.map((e) => `  - ${e}`),
+        `- **处理**: 请人工执行 \`rm -rf '${worktreePath}' && git worktree prune\` 清理残留目录与 git 管理记录。`,
+        branchName ? `- **分支**: 分支 "${branchName}" 未删除。` : ""
+      ].filter(Boolean).join(`
+`);
+    }
   }
   item.metadata["completed_at"] = new Date().toISOString();
   await writeState(ctx.worktree, state);
   const doneMessage = `任务组已完成并合并到 "${mergeTarget}"。`;
-  return checkboxWarning ? `${doneMessage}
-${checkboxWarning}` : doneMessage;
+  const notes = [cleanupNote, checkboxWarning, cleanupResidualWarning].filter(Boolean);
+  return notes.length > 0 ? `${doneMessage}
+${notes.join(`
+`)}` : doneMessage;
 }
 async function setUnattendedExecute(params, ctx) {
   assertOrchestrator(ctx, "opx_orch_set_unattended");
@@ -37507,7 +37613,7 @@ async function ensureDefaultUnattended(args, ctx) {
     }
   } catch {}
 }
-var PKG_VERSION = "0.130.0";
+var PKG_VERSION = "0.131.0";
 function buildMcpServer(worktree, opts = {}) {
   const mcp = new McpServer({ name: "openspec-agents", version: PKG_VERSION });
   for (const [name, spec] of Object.entries(TOOL_SPECS)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ifrankwang/openspec-agents",
-  "version": "0.130.0",
+  "version": "0.131.0",
   "description": "OpenSpec change orchestration plugin for AI coding agents (Claude Code, Codex, ZCode, DeepSeek Harness, OpenCode)",
   "author": "ifrankwang",
   "license": "MIT",

package/src/core/git.ts

@@ -1,6 +1,16 @@
 import path from "path"
 import { execFile } from "node:child_process"
-import { readFile, writeFile, stat } from "node:fs/promises"
+import { readFile, writeFile, stat, rm } from "node:fs/promises"
+
+/** 判断路径是否存在于磁盘（fs 层判断，git 命令结果不作为存在性依据）。 */
+async function pathExists(p: string): Promise<boolean> {
+  try {
+    await stat(p)
+    return true
+  } catch {
+    return false
+  }
+}
 
 export interface GitRunner {
   run(worktree: string, args: string[]): Promise<string>
@@ -54,6 +64,85 @@ export async function runGitChecked(
   return gitRunner.runChecked(worktree, args)
 }
 
+/** worktree 清理结果：成功判定以目录从磁盘真实消失为准，不信任单条 git 命令的退出码。 */
+export interface WorktreeRemovalResult {
+  /** 目录最终是否已从磁盘消失。 */
+  dirResolved: boolean
+  /** 目录是否经文件系统兜底删除后才消失（true 表示主路径未直接达成，发生了补救）。 */
+  dirResolvedByFallback: boolean
+  /** worktree prune 是否执行成功（幽灵管理记录清理）。 */
+  pruned: boolean
+  /** 分支删除结果：null=未指定分支或因目录残留被跳过；true/false=删除断言结果。 */
+  branchDeleted: boolean | null
+  /** 各环节失败原因聚合（人类可读），全部成功时为空数组。 */
+  errors: string[]
+}
+
+/**
+ * 删除任务组 worktree 并清理关联管理记录（收尾清理与 set_worktree 复用失败重建共用）。
+ *
+ * 序列：
+ * 1. 目录不存在 → 直接 prune（清理只残留管理记录的幽灵 worktree）；
+ * 2. 目录存在 → `git worktree remove --force`；命令失败或目录仍在磁盘时走补救链：
+ *    fs 递归删除 + prune（prune 失败仅记入 errors，不阻断）；
+ * 3. 目录确认消失后才 `git branch -D`；仍残留则跳过删分支并记入 errors，
+ *    防止孤儿分支掩盖问题、以及向不完整状态发出被 git 拒绝的命令。
+ *
+ * @param repoRoot 主仓库根路径（worktree 管理命令的 -C 目标）
+ * @param wtPath 待删除的 worktree 路径
+ * @param opts.branchName 关联分支名；缺省/null 时只做 worktree 侧清理
+ */
+export async function removeTaskGroupWorktree(
+  repoRoot: string,
+  wtPath: string,
+  opts: { branchName?: string | null } = {},
+): Promise<WorktreeRemovalResult> {
+  const result: WorktreeRemovalResult = { dirResolved: false, dirResolvedByFallback: false, pruned: false, branchDeleted: null, errors: [] }
+
+  if (!(await pathExists(wtPath))) {
+    const pruneRes = await runGitChecked(repoRoot, ["worktree", "prune"])
+    if (pruneRes.success) result.pruned = true
+    else result.errors.push(`worktree prune 失败：${pruneRes.stderr}`)
+    result.dirResolved = true
+  } else {
+    const rmRes = await runGitChecked(repoRoot, ["worktree", "remove", wtPath, "--force"])
+    if (!rmRes.success) result.errors.push(`git worktree remove 失败：${rmRes.stderr}`)
+    if (await pathExists(wtPath)) {
+      // 补救链：fs 物理删除目录 + prune 清理残留管理记录
+      try {
+        await rm(wtPath, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 })
+      } catch (e) {
+        result.errors.push(`文件系统兜底删除 "${wtPath}" 失败：${e instanceof Error ? e.message : String(e)}`)
+      }
+      const pruneRes = await runGitChecked(repoRoot, ["worktree", "prune"])
+      if (pruneRes.success) result.pruned = true
+      else result.errors.push(`worktree prune 失败：${pruneRes.stderr}`)
+      if (!(await pathExists(wtPath))) {
+        result.dirResolved = true
+        result.dirResolvedByFallback = true
+      }
+    } else {
+      result.dirResolved = true
+    }
+  }
+
+  if (!result.dirResolved) {
+    if (opts.branchName) {
+      result.errors.push(`目录 "${wtPath}" 未能删除，跳过分支 "${opts.branchName}" 的删除以保留排查线索`)
+    }
+    return result
+  }
+  if (opts.branchName) {
+    const branchRes = await runGitChecked(repoRoot, ["branch", "-D", opts.branchName])
+    if (branchRes.success) result.branchDeleted = true
+    else {
+      result.branchDeleted = false
+      result.errors.push(`删除分支 "${opts.branchName}" 失败：${branchRes.stderr}`)
+    }
+  }
+  return result
+}
+
 export async function getCurrentHead(worktree: string): Promise<string> {
   return runGit(worktree, ["rev-parse", "HEAD"])
 }

package/src/core/tools/lifecycle.ts

@@ -1,8 +1,9 @@
 import path from "path"
+import { rmdir } from "node:fs/promises"
 import type { OrchestrateState, TaskItem, TaskStatus, WorkflowMode } from "../types.ts"
 import { BUILD_PHASE_TARGETS, REVIEW_LAYERS, REVIEW_VERIFY_STEPS } from "../types.ts"
 import { agentToReviewLayer } from "../constants.ts"
-import { runGit, runGitChecked, getCurrentBranch, getMergeBase, isWorktreeClean, markTaskGroupCheckboxesComplete, mergeBranchToTarget, discoverDiskWorktrees, detectMainRepoPollution, detectChanges, type DetectChangesResult } from "../git.ts"
+import { runGit, runGitChecked, getCurrentBranch, getMergeBase, isWorktreeClean, markTaskGroupCheckboxesComplete, mergeBranchToTarget, discoverDiskWorktrees, detectMainRepoPollution, detectChanges, removeTaskGroupWorktree, type DetectChangesResult } from "../git.ts"
 import { readStateByWorktree, readStateByChangeId, writeState, writeContextToWorktree } from "../state.ts"
 import { generateIsolationNamespace } from "../namespace.ts"
 import { readExemptions } from "../exemptions.ts"
@@ -576,13 +577,13 @@ export async function setWorktreeExecute(params: SetWorktreeParams, ctx: ToolCon
         await bindWorktreeRefs(item, existingPath, branch, state.baseBranch)
         reused = true
       } else {
-        const rmResult = await runGitChecked(repoRoot, ["worktree", "remove", existingPath, "--force"])
-        if (!rmResult.success) {
-          throw new Error(`无法清理已有 worktree "${existingPath}"：${rmResult.stderr}`)
-        }
-        const branchRmResult = await runGitChecked(repoRoot, ["branch", "-D", branch])
-        if (!branchRmResult.success) {
-          throw new Error(`无法清理已有分支 "${branch}"：${branchRmResult.stderr}`)
+        // 复用失败的清理走共享清理函数：目录侧（git remove + fs 兜底 + prune）与分支删除统一语义
+        const cleanup = await removeTaskGroupWorktree(repoRoot, existingPath, { branchName: branch })
+        if (!cleanup.dirResolved || cleanup.branchDeleted === false) {
+          const problems: string[] = []
+          if (!cleanup.dirResolved) problems.push(`无法清理已有 worktree "${existingPath}"`)
+          if (cleanup.branchDeleted === false) problems.push(`无法清理已有分支 "${branch}"`)
+          throw new Error(`${problems.join("；")}：${cleanup.errors.join("；") || "原因未知"}\n请手动处理后重试。`)
         }
       }
     }
@@ -667,6 +668,22 @@ export async function statusExecute(params: StatusParams, ctx: ToolContext): Pro
   return renderWorkflowStatusView(item, workflow, rec, { agent, orchestrator: ctx.orchestrator, identityDeclared: ctx.identityDeclared }, { state, tg, mainPollution, toolChanges, exemptedHits, exemptionItems })
 }
 
+/**
+ * 收尾后清扫默认布局的空父目录（`.worktree/<changeId>` 与 `.worktree`）：
+ * 仅对这两级字面路径做非递归 rmdir（空目录才会成功），任一失败静默忽略。
+ * 自定义 worktree_path 时以「被删目录的实际 dirname === `.worktree/<changeId>`」判定是否可扫第一级，
+ * 第二级固定只试 `.worktree` 本身；其余任意父路径一律不做处理。
+ */
+async function sweepEmptyWorktreeParents(repoRoot: string, removedDir: string, changeId: string): Promise<void> {
+  const repoRootAbs = path.resolve(repoRoot)
+  const groupLevelDir = path.join(repoRootAbs, ".worktree", changeId)
+  const worktreeLevelDir = path.join(repoRootAbs, ".worktree")
+  if (path.dirname(path.resolve(removedDir)) === groupLevelDir) {
+    try { await rmdir(groupLevelDir) } catch {}
+  }
+  try { await rmdir(worktreeLevelDir) } catch {}
+}
+
 export async function completeTaskGroupExecute(params: { change_id: string }, ctx: ToolContext): Promise<string> {
   assertOrchestrator(ctx, "opx_orch_complete_task_group")
   const state = await readStateByWorktree(ctx.worktree, params.change_id)
@@ -731,17 +748,40 @@ export async function completeTaskGroupExecute(params: { change_id: string }, ct
       ].join("\n")
     }
   }
-  if (worktreePath && branchName) {
-    try {
-      await runGit(ctx.worktree, ["worktree", "remove", worktreePath, "--force"])
-      await runGit(ctx.worktree, ["branch", "-D", branchName])
-    } catch {
+  // 收尾清理：只要记录了 worktree_path 就执行；branch_name 缺省时仅做 worktree 侧清理。
+  // 残留不阻断收尾：completed_at 照写，残留信息写入 metadata.cleanup_residual 并在返回体给出人工处理命令。
+  let cleanupNote = ""
+  let cleanupResidualWarning = ""
+  if (worktreePath) {
+    const cleanup = await removeTaskGroupWorktree(ctx.worktree, worktreePath, { branchName })
+    if (cleanup.dirResolved) {
+      await sweepEmptyWorktreeParents(ctx.worktree, worktreePath, params.change_id)
+      const successNotes: string[] = []
+      if (cleanup.dirResolvedByFallback) {
+        successNotes.push("- **cleanup**: git worktree remove 未直接移除目录，已按文件系统兜底删除并 prune 管理记录。")
+      }
+      if (cleanup.errors.length > 0) {
+        successNotes.push(`- **cleanup 部分告警**: ${cleanup.errors.join("；")}`)
+      }
+      cleanupNote = successNotes.join("\n")
+    } else {
+      item.metadata["cleanup_residual"] = { worktree_path: worktreePath, errors: cleanup.errors }
+      cleanupResidualWarning = [
+        "",
+        "## ⚠️ worktree 清理残留（不影响收尾）",
+        `- **残留路径**: \`${worktreePath}\``,
+        "- **原因**:",
+        ...cleanup.errors.map((e) => `  - ${e}`),
+        `- **处理**: 请人工执行 \`rm -rf '${worktreePath}' && git worktree prune\` 清理残留目录与 git 管理记录。`,
+        branchName ? `- **分支**: 分支 "${branchName}" 未删除。` : "",
+      ].filter(Boolean).join("\n")
     }
   }
   item.metadata["completed_at"] = new Date().toISOString()
   await writeState(ctx.worktree, state)
   const doneMessage = `任务组已完成并合并到 "${mergeTarget}"。`
-  return checkboxWarning ? `${doneMessage}\n${checkboxWarning}` : doneMessage
+  const notes = [cleanupNote, checkboxWarning, cleanupResidualWarning].filter(Boolean)
+  return notes.length > 0 ? `${doneMessage}\n${notes.join("\n")}` : doneMessage
 }
 
 export async function setUnattendedExecute(params: UnattendedParams, ctx: ToolContext): Promise<string> {