patchwarden 1.5.0 → 1.6.1

package/src/goal/specKitImport.ts

@@ -0,0 +1,355 @@
+/**
+ * v0.8.0: Spec Kit tasks 导入 — 将 Spec Kit 的 spec/tasks 结构转换为 Goal Session 子目标。
+ *
+ * - 解析 Spec Kit JSON（parseSpecKitJson）
+ * - 幂等导入：按 external_ref 去重，重复导入不产生重复 subgoal
+ * - 依赖解析：将 task.depends_on（external_ref 引用）解析为本地 subgoal id
+ * - 验收标准映射：input.acceptance → GoalStatus.acceptance_criteria
+ *
+ * 不引入第三方依赖，仅用 Node.js 内置模块。
+ */
+
+import { PatchWardenError } from "../errors.js";
+import { addSubgoal, type GoalStatus } from "./goalStatus.js";
+import { mutateGoalStatus } from "./goalStore.js";
+
+// ── 类型定义 ──────────────────────────────────────────────────────
+
+export interface SpecKitTask {
+  id: string;
+  desc: string;
+  files?: string[];
+  /** 引用其他 task 的 id（external_ref） */
+  depends_on?: string[];
+}
+
+export interface SpecKitInput {
+  spec: string;
+  tasks: SpecKitTask[];
+  acceptance?: string[];
+}
+
+export interface SpecKitImportResult {
+  goal_id: string;
+  spec_name: string;
+  created_count: number;
+  existing_count: number;
+  subgoal_ids: string[];
+}
+
+// ── JSON 解析 ─────────────────────────────────────────────────────
+
+/**
+ * 解析 Spec Kit JSON 文本并验证结构。
+ *
+ * 必须包含：
+ * - spec: 非空字符串
+ * - tasks: 数组，每个元素含 id（字符串）和 desc（字符串）
+ *
+ * 可选：
+ * - acceptance: 字符串数组
+ *
+ * 解析失败或结构不合法时抛出 PatchWardenError("invalid_spec_kit_json" | "invalid_spec_kit_input")。
+ */
+export function parseSpecKitJson(jsonText: string): SpecKitInput {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(jsonText);
+  } catch (e) {
+    throw new PatchWardenError(
+      "invalid_spec_kit_json",
+      `Failed to parse Spec Kit JSON: ${e instanceof Error ? e.message : String(e)}`,
+      "Ensure the input is valid JSON.",
+      true,
+      {}
+    );
+  }
+
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new PatchWardenError(
+      "invalid_spec_kit_input",
+      "Spec Kit JSON must be a JSON object",
+      'Ensure the top-level value is an object with "spec" and "tasks" fields.',
+      true,
+      { actual_type: Array.isArray(parsed) ? "array" : typeof parsed }
+    );
+  }
+
+  const obj = parsed as Record<string, unknown>;
+
+  if (typeof obj.spec !== "string" || obj.spec === "") {
+    throw new PatchWardenError(
+      "invalid_spec_kit_input",
+      'Spec Kit JSON must contain a non-empty "spec" string field',
+      'Add a "spec" field with a non-empty string value describing the specification name.',
+      true,
+      { spec: obj.spec }
+    );
+  }
+
+  if (!Array.isArray(obj.tasks)) {
+    throw new PatchWardenError(
+      "invalid_spec_kit_input",
+      'Spec Kit JSON must contain a "tasks" array field',
+      'Add a "tasks" field with an array of task objects (each with "id" and "desc").',
+      true,
+      { tasks_type: Array.isArray(obj.tasks) ? "array" : typeof obj.tasks }
+    );
+  }
+
+  const tasks: SpecKitTask[] = [];
+  for (let i = 0; i < obj.tasks.length; i++) {
+    const raw = obj.tasks[i];
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+      throw new PatchWardenError(
+        "invalid_spec_kit_input",
+        `Spec Kit task at index ${i} must be an object`,
+        "Each task must be an object with at least \"id\" and \"desc\" string fields.",
+        true,
+        { task_index: i, actual_type: typeof raw }
+      );
+    }
+    const t = raw as Record<string, unknown>;
+    if (typeof t.id !== "string" || t.id === "") {
+      throw new PatchWardenError(
+        "invalid_spec_kit_input",
+        `Spec Kit task at index ${i} must have a non-empty "id" string`,
+        "Ensure each task has a unique non-empty string \"id\".",
+        true,
+        { task_index: i, id: t.id }
+      );
+    }
+    if (typeof t.desc !== "string") {
+      throw new PatchWardenError(
+        "invalid_spec_kit_input",
+        `Spec Kit task at index ${i} (id="${t.id}") must have a "desc" string`,
+        "Ensure each task has a \"desc\" string describing the task.",
+        true,
+        { task_index: i, id: t.id, desc_type: typeof t.desc }
+      );
+    }
+
+    const task: SpecKitTask = { id: t.id, desc: t.desc };
+    if (Array.isArray(t.files)) {
+      task.files = t.files.filter((f): f is string => typeof f === "string");
+    }
+    if (Array.isArray(t.depends_on)) {
+      task.depends_on = t.depends_on.filter(
+        (d): d is string => typeof d === "string"
+      );
+    }
+    tasks.push(task);
+  }
+
+  const result: SpecKitInput = { spec: obj.spec, tasks };
+  if (Array.isArray(obj.acceptance)) {
+    result.acceptance = obj.acceptance.filter(
+      (a): a is string => typeof a === "string"
+    );
+  }
+
+  return result;
+}
+
+// ── 导入实现 ──────────────────────────────────────────────────────
+
+/**
+ * 将 Spec Kit tasks 导入到指定 Goal Session，创建对应的 subgoal。
+ *
+ * 行为：
+ * - 验证 input（spec 非空、tasks 为数组）
+ * - 幂等去重：按 external_ref（task.id）匹配现有 subgoal，已存在则跳过
+ * - 依赖解析：将 task.depends_on（external_ref）解析为本地 subgoal id
+ *   - 先创建无依赖的 subgoal，再处理有依赖的，支持多级依赖
+ *   - 依赖的 task 在同一批次中：用刚创建的 subgoal_id
+ *   - 依赖的 task 不存在：忽略该依赖并记录 warning（console.warn）
+ * - 验收标准：input.acceptance 非空时写入 GoalStatus.acceptance_criteria
+ * - 持久化：用 writeGoalStatus 原子写入
+ *
+ * @param goalId       目标 Goal 标识
+ * @param input        Spec Kit 输入（spec + tasks + acceptance）
+ * @param options      可选配置：workspaceRoot 用于测试
+ * @returns SpecKitImportResult
+ */
+export function importSpecKitTasks(
+  goalId: string,
+  input: SpecKitInput,
+  options?: { workspaceRoot?: string }
+): SpecKitImportResult {
+  // ── 验证 ───────────────────────────────────────────────────
+  if (!input || typeof input !== "object") {
+    throw new PatchWardenError(
+      "invalid_spec_kit_input",
+      "Spec Kit input must be an object",
+      "Pass a SpecKitInput object with spec, tasks, and optional acceptance fields.",
+      true,
+      {}
+    );
+  }
+  if (typeof input.spec !== "string" || input.spec === "") {
+    throw new PatchWardenError(
+      "invalid_spec_kit_input",
+      'Spec Kit input must contain a non-empty "spec" string',
+      "Ensure input.spec is a non-empty string.",
+      true,
+      { spec: input.spec }
+    );
+  }
+  if (!Array.isArray(input.tasks)) {
+    throw new PatchWardenError(
+      "invalid_spec_kit_input",
+      'Spec Kit input must contain a "tasks" array',
+      "Ensure input.tasks is an array of SpecKitTask objects.",
+      true,
+      { tasks_type: Array.isArray(input.tasks) ? "array" : typeof input.tasks }
+    );
+  }
+
+  const workspaceRoot = options?.workspaceRoot;
+
+  return mutateGoalStatus(goalId, (currentGoalStatus) => {
+  let goalStatus: GoalStatus = currentGoalStatus;
+
+  // ── 构建 external_ref → subgoal_id 映射（现有 subgoal）─────
+  const refToSubgoalId = new Map<string, string>();
+  for (const sg of goalStatus.subgoals) {
+    if (sg.external_ref) {
+      refToSubgoalId.set(sg.external_ref, sg.id);
+    }
+  }
+
+  // ── 幂等去重：区分新 task 和已存在的 task ─────────────────
+  const newTasks: SpecKitTask[] = [];
+  let existingCount = 0;
+  for (const task of input.tasks) {
+    if (refToSubgoalId.has(task.id)) {
+      existingCount++;
+    } else {
+      newTasks.push(task);
+    }
+  }
+
+  // 新批次中所有 task id 集合（用于判断依赖是否在同批次）
+  const newTaskIds = new Set(newTasks.map((t) => t.id));
+
+  // ── 按依赖顺序创建 subgoal（拓扑排序，迭代多轮）────────────
+  const createdIds: string[] = [];
+  let remaining = [...newTasks];
+
+  // 辅助：创建单个 subgoal 并设置 external_ref / scope_hints
+  const createSubgoalForTask = (
+    gs: GoalStatus,
+    task: SpecKitTask,
+    resolvedDeps: string[]
+  ): { goalStatus: GoalStatus; subgoalId: string } => {
+    const { goalStatus: newGs, subgoalId } = addSubgoal(gs, task.desc, resolvedDeps);
+
+    // 新 subgoal 是数组最后一个元素，追加 external_ref 和 scope_hints
+    const subgoals = [...newGs.subgoals];
+    const lastIdx = subgoals.length - 1;
+    const updated: typeof subgoals[number] = {
+      ...subgoals[lastIdx],
+      external_ref: task.id,
+    };
+    if (task.files && task.files.length > 0) {
+      updated.scope_hints = [...task.files];
+    }
+    subgoals[lastIdx] = updated;
+
+    return { goalStatus: { ...newGs, subgoals }, subgoalId };
+  };
+
+  while (remaining.length > 0) {
+    const stillRemaining: SpecKitTask[] = [];
+    let progress = false;
+
+    // 正向遍历：保持输入顺序，先创建的 task 可被同批次后续 task 依赖
+    for (const task of remaining) {
+      const deps = task.depends_on ?? [];
+
+      const resolvedDeps: string[] = [];
+      let hasUnresolvedInBatch = false;
+
+      for (const dep of deps) {
+        if (refToSubgoalId.has(dep)) {
+          // 依赖已存在（已有 subgoal 或本批次已创建）
+          resolvedDeps.push(refToSubgoalId.get(dep)!);
+        } else if (newTaskIds.has(dep)) {
+          // 依赖同批次中尚未创建的 task
+          hasUnresolvedInBatch = true;
+        } else {
+          // 依赖的 task 不存在任何地方：忽略并记录 warning
+          console.warn(
+            `[specKitImport] Task "${task.id}" depends on non-existent task "${dep}"; ignoring this dependency.`
+          );
+        }
+      }
+
+      if (!hasUnresolvedInBatch) {
+        const { goalStatus: newGs, subgoalId } = createSubgoalForTask(
+          goalStatus,
+          task,
+          resolvedDeps
+        );
+        goalStatus = newGs;
+        refToSubgoalId.set(task.id, subgoalId);
+        createdIds.push(subgoalId);
+        progress = true;
+      } else {
+        stillRemaining.push(task);
+      }
+    }
+
+    remaining = stillRemaining;
+
+    if (!progress && remaining.length > 0) {
+      // 检测到循环依赖：强制创建剩余 task，忽略未解析的同批次依赖
+      for (const task of remaining) {
+        const deps = task.depends_on ?? [];
+        const resolvedDeps: string[] = [];
+        for (const dep of deps) {
+          if (refToSubgoalId.has(dep)) {
+            resolvedDeps.push(refToSubgoalId.get(dep)!);
+          } else if (newTaskIds.has(dep)) {
+            console.warn(
+              `[specKitImport] Circular dependency detected: task "${task.id}" depends on "${dep}" which could not be resolved; ignoring this dependency.`
+            );
+          } else {
+            console.warn(
+              `[specKitImport] Task "${task.id}" depends on non-existent task "${dep}"; ignoring this dependency.`
+            );
+          }
+        }
+        const { goalStatus: newGs, subgoalId } = createSubgoalForTask(
+          goalStatus,
+          task,
+          resolvedDeps
+        );
+        goalStatus = newGs;
+        refToSubgoalId.set(task.id, subgoalId);
+        createdIds.push(subgoalId);
+      }
+      break;
+    }
+  }
+
+  // ── 验收标准 ───────────────────────────────────────────────
+  if (input.acceptance && input.acceptance.length > 0) {
+    goalStatus = {
+      ...goalStatus,
+      acceptance_criteria: [...input.acceptance],
+    };
+  }
+
+  return {
+    next: goalStatus,
+    result: {
+      goal_id: goalId,
+      spec_name: input.spec,
+      created_count: createdIds.length,
+      existing_count: existingCount,
+      subgoal_ids: createdIds,
+    },
+  };
+  }, workspaceRoot);
+}

package/src/goal/subgoalSync.ts

@@ -9,8 +9,9 @@
 
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { readGoalStatus, writeGoalStatus } from "./goalStore.js";
+import { mutateGoalStatus } from "./goalStore.js";
 import { updateSubgoalStatus } from "./goalStatus.js";
+import { logger } from "../logging.js";
 
 // ── 同步函数 ──────────────────────────────────────────────────────
 
@@ -38,17 +39,21 @@ export function syncSubgoalOnTaskDone(
   if (!goalId || !subgoalId) return;
 
   try {
-    const goalStatus = readGoalStatus(goalId, workspaceRoot);
-    const subgoal = goalStatus.subgoals.find((s) => s.id === subgoalId);
-    if (!subgoal) return;
-    if (subgoal.status !== "running") return;
-
-    const updated = updateSubgoalStatus(goalStatus, subgoalId, "done_by_agent");
-    writeGoalStatus(goalId, updated, workspaceRoot);
+    mutateGoalStatus(goalId, (goalStatus) => {
+      const subgoal = goalStatus.subgoals.find((entry) => entry.id === subgoalId);
+      if (!subgoal || subgoal.status !== "running") {
+        return { result: undefined };
+      }
+      return {
+        next: updateSubgoalStatus(goalStatus, subgoalId, "done_by_agent"),
+        result: undefined,
+      };
+    }, workspaceRoot);
   } catch (err) {
     // subgoal 同步失败不应影响任务完成流程，只记录到 stderr
-    console.error(
-      `[goal] syncSubgoalOnTaskDone failed for task ${taskId}: ${err instanceof Error ? err.message : String(err)}`
+    logger.error(
+      `[goal] syncSubgoalOnTaskDone failed for task ${taskId}`,
+      { error: err instanceof Error ? err.message : String(err) },
     );
   }
 }

package/src/goal/worktreeManager.ts

@@ -23,17 +23,18 @@ import {
   existsSync,
   mkdirSync,
   readFileSync,
-  renameSync,
-  writeFileSync,
   rmSync,
 } from "node:fs";
-import { join } from "node:path";
+import { join, normalize } from "node:path";
 import { execFileSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { getConfig } from "../config.js";
-import { guardWorkspacePath } from "../security/pathGuard.js";
+import { guardPath, guardWorkspacePath } from "../security/pathGuard.js";
 import { guardSensitivePath } from "../security/sensitiveGuard.js";
 import { PatchWardenError } from "../errors.js";
+import { buildGitEnvironment, resolveTrustedExecutable } from "../runner/processSecurity.js";
+import { atomicWriteJsonFileSync } from "../utils/atomicFile.js";
+import { withFileLockSync } from "../utils/lockedJsonFile.js";
 
 // ── 类型定义 ──────────────────────────────────────────────────────
 
@@ -56,9 +57,12 @@ export const WorktreeDir = "_workspacetrees";
 
 /** 归档目录名（discard 后保留状态），位于 .patchwarden 下，始终为安全路径。 */
 const WORKTREE_ARCHIVE_DIR = ".patchwarden/worktree-archive";
+const WORKTREE_LOCK_DIR = ".patchwarden/worktree-locks";
 
 const GIT_TIMEOUT_MS = 30000;
 const GIT_BRANCH_TIMEOUT_MS = 15000;
+const WORKTREE_ID_MAX_LENGTH = 32;
+const WORKTREE_ID_PATTERN = /^wt_[a-z0-9]{1,16}_[a-f0-9]{12}$/;
 
 // ── 辅助：解析 workspaceRoot ──────────────────────────────────────
 
@@ -66,20 +70,43 @@ function resolveWorkspaceRoot(workspaceRoot?: string): string {
   return workspaceRoot ?? getConfig().workspaceRoot;
 }
 
+/** Accept only IDs emitted by generateWorktreeId(). */
+export function assertValidWorktreeId(worktreeId: string): void {
+  if (
+    worktreeId.length > WORKTREE_ID_MAX_LENGTH ||
+    !WORKTREE_ID_PATTERN.test(worktreeId)
+  ) {
+    throw new PatchWardenError(
+      "invalid_worktree_id",
+      "Invalid worktree id. Expected the wt_<base36 timestamp>_<12 hex chars> format.",
+      "Use the worktree_id returned by create_subgoal_task.",
+      true,
+      { worktree_id_length: worktreeId.length }
+    );
+  }
+}
+
 // ── 目录路径解析 ──────────────────────────────────────────────────
 
 /**
  * 返回 `<workspaceRoot>/_workspacetrees` 目录路径。不自动创建目录。
  */
 export function getWorktreesDir(workspaceRoot?: string): string {
-  return join(resolveWorkspaceRoot(workspaceRoot), WorktreeDir);
+  const wsRoot = resolveWorkspaceRoot(workspaceRoot);
+  return guardPath(join(wsRoot, WorktreeDir), wsRoot, WorktreeDir);
 }
 
 /**
  * 返回 `<getWorktreesDir()>/<worktreeId>` 路径。
  */
 export function getWorktreeDir(worktreeId: string, workspaceRoot?: string): string {
-  return join(getWorktreesDir(workspaceRoot), worktreeId);
+  assertValidWorktreeId(worktreeId);
+  const wsRoot = resolveWorkspaceRoot(workspaceRoot);
+  return guardPath(
+    join(getWorktreesDir(wsRoot), worktreeId),
+    wsRoot,
+    WorktreeDir
+  );
 }
 
 // ── ID 与 branch 生成 ─────────────────────────────────────────────
@@ -105,23 +132,110 @@ function sanitizeBranchSegment(value: string): string {
   return cleaned === "" ? "x" : cleaned;
 }
 
+function samePath(left: string, right: string): boolean {
+  const normalizedLeft = normalize(left);
+  const normalizedRight = normalize(right);
+  return process.platform === "win32"
+    ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
+    : normalizedLeft === normalizedRight;
+}
+
+function withWorktreeRepositoryLock<R>(workspaceRoot: string, action: () => R): R {
+  const wsRoot = resolveWorkspaceRoot(workspaceRoot);
+  const lockDir = guardPath(join(wsRoot, WORKTREE_LOCK_DIR), wsRoot, WORKTREE_LOCK_DIR);
+  mkdirSync(lockDir, { recursive: true });
+  return withFileLockSync(join(lockDir, "repository-mutation"), action, {
+    waitMs: 0,
+    busyError: () => new PatchWardenError(
+      "worktree_busy",
+      "Another managed worktree operation is already changing this repository.",
+      "Retry after the active create, merge, or discard operation finishes.",
+      true,
+    ),
+  });
+}
+
+function invalidWorktreeStatus(
+  worktreeId: string,
+  message: string
+): never {
+  throw new PatchWardenError(
+    "invalid_worktree_status",
+    `Invalid worktree status for "${worktreeId}": ${message}`,
+    "Do not edit worktree_status.json manually; recreate the isolated worktree.",
+    true,
+    { worktree_id: worktreeId }
+  );
+}
+
+function validateWorktreeStatus(
+  value: unknown,
+  worktreeId: string,
+  workspaceRoot: string,
+  expectedPath: string
+): WorktreeStatus {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return invalidWorktreeStatus(worktreeId, "expected a JSON object");
+  }
+
+  const candidate = value as Record<string, unknown>;
+  const statusValues = new Set(["active", "merged", "discarded"]);
+  if (
+    typeof candidate.worktree_id !== "string" ||
+    typeof candidate.goal_id !== "string" ||
+    typeof candidate.subgoal_id !== "string" ||
+    typeof candidate.path !== "string" ||
+    typeof candidate.created_at !== "string" ||
+    typeof candidate.status !== "string" ||
+    !statusValues.has(candidate.status) ||
+    typeof candidate.branch !== "string"
+  ) {
+    return invalidWorktreeStatus(worktreeId, "missing or invalid required fields");
+  }
+
+  if (candidate.worktree_id !== worktreeId) {
+    return invalidWorktreeStatus(worktreeId, "worktree_id does not match its directory");
+  }
+
+  let guardedStatusPath: string;
+  try {
+    guardedStatusPath = guardPath(candidate.path, workspaceRoot, WorktreeDir);
+  } catch {
+    return invalidWorktreeStatus(worktreeId, "path is outside the managed worktree root");
+  }
+  if (!samePath(guardedStatusPath, expectedPath)) {
+    return invalidWorktreeStatus(worktreeId, "path does not match its directory");
+  }
+
+  const expectedBranch = `pw-${sanitizeBranchSegment(candidate.goal_id)}-${sanitizeBranchSegment(candidate.subgoal_id)}`;
+  if (candidate.branch !== expectedBranch) {
+    return invalidWorktreeStatus(worktreeId, "branch does not match goal and subgoal metadata");
+  }
+
+  if (
+    (candidate.merged_at !== undefined && typeof candidate.merged_at !== "string") ||
+    (candidate.discarded_at !== undefined && typeof candidate.discarded_at !== "string")
+  ) {
+    return invalidWorktreeStatus(worktreeId, "invalid lifecycle timestamp");
+  }
+
+  return candidate as unknown as WorktreeStatus;
+}
+
 // ── 原子写 ────────────────────────────────────────────────────────
 
-/**
- * 原子写入 status 文件：先写到 `.tmp` 文件，再 renameSync。
- * 参考 goalStore.ts writeGoalStatus 的模式。
- */
 function writeStatusAtomic(statusFilePath: string, status: WorktreeStatus): void {
-  const tmpPath = statusFilePath + ".tmp";
-  writeFileSync(tmpPath, JSON.stringify(status, null, 2) + "\n", "utf-8");
-  renameSync(tmpPath, statusFilePath);
+  atomicWriteJsonFileSync(statusFilePath, status);
 }
 
 function runGit(args: string[], cwd: string, timeoutMs: number): void {
-  execFileSync("git", args, {
+  const env = buildGitEnvironment(cwd);
+  execFileSync(resolveTrustedExecutable("git", cwd, { pathValue: env.PATH }), args, {
     cwd,
     timeout: timeoutMs,
     stdio: ["pipe", "pipe", "pipe"],
+    windowsHide: true,
+    env,
   });
 }
 
@@ -157,6 +271,7 @@ export function createWorktree(
   subgoalId: string,
   workspaceRoot: string
 ): { worktreeId: string; worktreePath: string; branch: string } {
+  return withWorktreeRepositoryLock(workspaceRoot, () => {
   const wsRoot = resolveWorkspaceRoot(workspaceRoot);
 
   const worktreeId = generateWorktreeId();
@@ -222,6 +337,7 @@ export function createWorktree(
       }
     );
   }
+  });
 }
 
 /**
@@ -241,12 +357,13 @@ export function readWorktreeStatus(
   const statusFilePath = join(worktreePath, "worktree_status.json");
   if (!existsSync(statusFilePath)) return null;
 
+  let parsed: unknown;
   try {
-    const raw = readFileSync(statusFilePath, "utf-8");
-    return JSON.parse(raw) as WorktreeStatus;
+    parsed = JSON.parse(readFileSync(statusFilePath, "utf-8"));
   } catch {
-    return null;
+    return invalidWorktreeStatus(worktreeId, "file is not valid JSON");
   }
+  return validateWorktreeStatus(parsed, worktreeId, wsRoot, worktreePath);
 }
 
 /**
@@ -264,6 +381,7 @@ export function mergeWorktree(
   worktreeId: string,
   workspaceRoot: string
 ): { status: "merged" } {
+  return withWorktreeRepositoryLock(workspaceRoot, () => {
   const wsRoot = resolveWorkspaceRoot(workspaceRoot);
   const worktreePath = getWorktreeDir(worktreeId, workspaceRoot);
 
@@ -313,6 +431,7 @@ export function mergeWorktree(
   writeStatusAtomic(statusFilePath, updatedStatus);
 
   return { status: "merged" };
+  });
 }
 
 /**
@@ -333,6 +452,7 @@ export function discardWorktree(
   worktreeId: string,
   workspaceRoot: string
 ): { status: "discarded" } {
+  return withWorktreeRepositoryLock(workspaceRoot, () => {
   const wsRoot = resolveWorkspaceRoot(workspaceRoot);
   const worktreePath = getWorktreeDir(worktreeId, workspaceRoot);
 
@@ -364,10 +484,6 @@ export function discardWorktree(
   try {
     runGit(["worktree", "remove", "--force", worktreePath], wsRoot, GIT_TIMEOUT_MS);
   } catch (err) {
-    // git remove 失败时再尝试直接删目录（best effort），然后抛错
-    try {
-      rmSync(worktreePath, { recursive: true, force: true });
-    } catch { /* ignore */ }
     throw new PatchWardenError(
       "worktree_discard_failed",
       `Failed to remove worktree "${worktreeId}": ${gitErrorMessage(err)}`,
@@ -391,7 +507,7 @@ export function discardWorktree(
 
   const archiveDir = join(wsRoot, WORKTREE_ARCHIVE_DIR);
   guardWorkspacePath(archiveDir, wsRoot);
-  // .patchwarden 路径在 sensitiveGuard 中始终视为安全（SAFE_PREFIX），无需额外校验
+  // The archive path is workspace-confined and contains only managed status metadata.
 
   try {
     mkdirSync(archiveDir, { recursive: true });
@@ -401,4 +517,5 @@ export function discardWorktree(
   writeStatusAtomic(archiveFilePath, archivedStatus);
 
   return { status: "discarded" };
+  });
 }