patchwarden 1.5.0 → 1.6.1

package/dist/goal/worktreeManager.js

@@ -18,37 +18,53 @@
  * 所有文件系统函数都接受可选的 workspaceRoot 参数用于测试；
  * 默认从 getConfig().workspaceRoot 读取。
  */
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, rmSync, } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, rmSync, } from "node:fs";
+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";
 // ── 常量 ──────────────────────────────────────────────────────────
 /** worktree 根目录名，放在 workspaceRoot 下。 */
 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 ──────────────────────────────────────
 function resolveWorkspaceRoot(workspaceRoot) {
     return workspaceRoot ?? getConfig().workspaceRoot;
 }
+/** Accept only IDs emitted by generateWorktreeId(). */
+export function assertValidWorktreeId(worktreeId) {
+    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) {
-    return join(resolveWorkspaceRoot(workspaceRoot), WorktreeDir);
+    const wsRoot = resolveWorkspaceRoot(workspaceRoot);
+    return guardPath(join(wsRoot, WorktreeDir), wsRoot, WorktreeDir);
 }
 /**
  * 返回 `<getWorktreesDir()>/<worktreeId>` 路径。
  */
 export function getWorktreeDir(worktreeId, workspaceRoot) {
-    return join(getWorktreesDir(workspaceRoot), worktreeId);
+    assertValidWorktreeId(worktreeId);
+    const wsRoot = resolveWorkspaceRoot(workspaceRoot);
+    return guardPath(join(getWorktreesDir(wsRoot), worktreeId), wsRoot, WorktreeDir);
 }
 // ── ID 与 branch 生成 ─────────────────────────────────────────────
 /**
@@ -70,21 +86,76 @@ function sanitizeBranchSegment(value) {
     const cleaned = value.replace(/[^a-zA-Z0-9_-]/g, "_");
     return cleaned === "" ? "x" : cleaned;
 }
+function samePath(left, right) {
+    const normalizedLeft = normalize(left);
+    const normalizedRight = normalize(right);
+    return process.platform === "win32"
+        ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
+        : normalizedLeft === normalizedRight;
+}
+function withWorktreeRepositoryLock(workspaceRoot, action) {
+    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, message) {
+    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, worktreeId, workspaceRoot, expectedPath) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return invalidWorktreeStatus(worktreeId, "expected a JSON object");
+    }
+    const candidate = value;
+    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;
+    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;
+}
 // ── 原子写 ────────────────────────────────────────────────────────
-/**
- * 原子写入 status 文件：先写到 `.tmp` 文件，再 renameSync。
- * 参考 goalStore.ts writeGoalStatus 的模式。
- */
 function writeStatusAtomic(statusFilePath, status) {
-    const tmpPath = statusFilePath + ".tmp";
-    writeFileSync(tmpPath, JSON.stringify(status, null, 2) + "\n", "utf-8");
-    renameSync(tmpPath, statusFilePath);
+    atomicWriteJsonFileSync(statusFilePath, status);
 }
 function runGit(args, cwd, timeoutMs) {
-    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,
     });
 }
 function gitErrorMessage(err) {
@@ -114,62 +185,64 @@ function gitErrorMessage(err) {
  * @returns { worktreeId, worktreePath, branch }
  */
 export function createWorktree(goalId, subgoalId, workspaceRoot) {
-    const wsRoot = resolveWorkspaceRoot(workspaceRoot);
-    const worktreeId = generateWorktreeId();
-    const worktreePath = getWorktreeDir(worktreeId, workspaceRoot);
-    const branch = `pw-${sanitizeBranchSegment(goalId)}-${sanitizeBranchSegment(subgoalId)}`;
-    // 安全：校验 worktreePath 在 workspaceRoot 内且非敏感路径
-    guardWorkspacePath(worktreePath, wsRoot);
-    guardSensitivePath(worktreePath);
-    let worktreeCreated = false;
-    let branchCreated = false;
-    try {
-        runGit(["worktree", "add", "-b", branch, worktreePath], wsRoot, GIT_TIMEOUT_MS);
-        worktreeCreated = true;
-        branchCreated = true;
-        // 原子写入 worktree_status.json（worktreePath 是新目录，无旧 status，直接 tmp + rename）
-        const statusFilePath = join(worktreePath, "worktree_status.json");
-        const now = new Date().toISOString();
-        const status = {
-            worktree_id: worktreeId,
-            goal_id: goalId,
-            subgoal_id: subgoalId,
-            path: worktreePath,
-            created_at: now,
-            status: "active",
-            branch,
-        };
-        writeStatusAtomic(statusFilePath, status);
-        return { worktreeId, worktreePath, branch };
-    }
-    catch (err) {
-        // 清理半成品
-        if (worktreeCreated) {
-            try {
-                rmSync(worktreePath, { recursive: true, force: true });
-            }
-            catch { /* ignore */ }
-            // rmSync 可能无法清除 git 的 worktree 元数据，再尝试 git worktree remove
-            try {
-                runGit(["worktree", "remove", "--force", worktreePath], wsRoot, GIT_BRANCH_TIMEOUT_MS);
-            }
-            catch { /* ignore */ }
+    return withWorktreeRepositoryLock(workspaceRoot, () => {
+        const wsRoot = resolveWorkspaceRoot(workspaceRoot);
+        const worktreeId = generateWorktreeId();
+        const worktreePath = getWorktreeDir(worktreeId, workspaceRoot);
+        const branch = `pw-${sanitizeBranchSegment(goalId)}-${sanitizeBranchSegment(subgoalId)}`;
+        // 安全：校验 worktreePath 在 workspaceRoot 内且非敏感路径
+        guardWorkspacePath(worktreePath, wsRoot);
+        guardSensitivePath(worktreePath);
+        let worktreeCreated = false;
+        let branchCreated = false;
+        try {
+            runGit(["worktree", "add", "-b", branch, worktreePath], wsRoot, GIT_TIMEOUT_MS);
+            worktreeCreated = true;
+            branchCreated = true;
+            // 原子写入 worktree_status.json（worktreePath 是新目录，无旧 status，直接 tmp + rename）
+            const statusFilePath = join(worktreePath, "worktree_status.json");
+            const now = new Date().toISOString();
+            const status = {
+                worktree_id: worktreeId,
+                goal_id: goalId,
+                subgoal_id: subgoalId,
+                path: worktreePath,
+                created_at: now,
+                status: "active",
+                branch,
+            };
+            writeStatusAtomic(statusFilePath, status);
+            return { worktreeId, worktreePath, branch };
         }
-        if (branchCreated) {
-            try {
-                runGit(["branch", "-D", branch], wsRoot, GIT_BRANCH_TIMEOUT_MS);
+        catch (err) {
+            // 清理半成品
+            if (worktreeCreated) {
+                try {
+                    rmSync(worktreePath, { recursive: true, force: true });
+                }
+                catch { /* ignore */ }
+                // rmSync 可能无法清除 git 的 worktree 元数据，再尝试 git worktree remove
+                try {
+                    runGit(["worktree", "remove", "--force", worktreePath], wsRoot, GIT_BRANCH_TIMEOUT_MS);
+                }
+                catch { /* ignore */ }
             }
-            catch { /* ignore — branch 可能未创建或已随 worktree remove 清理 */ }
+            if (branchCreated) {
+                try {
+                    runGit(["branch", "-D", branch], wsRoot, GIT_BRANCH_TIMEOUT_MS);
+                }
+                catch { /* ignore — branch 可能未创建或已随 worktree remove 清理 */ }
+            }
+            if (err instanceof PatchWardenError)
+                throw err;
+            throw new PatchWardenError("worktree_create_failed", `Failed to create worktree for goal "${goalId}" / subgoal "${subgoalId}": ${gitErrorMessage(err)}`, "Ensure workspaceRoot is a git repository with at least one commit, and the worktree path is writable.", true, {
+                goal_id: goalId,
+                subgoal_id: subgoalId,
+                branch,
+                worktree_path: worktreePath,
+            });
         }
-        if (err instanceof PatchWardenError)
-            throw err;
-        throw new PatchWardenError("worktree_create_failed", `Failed to create worktree for goal "${goalId}" / subgoal "${subgoalId}": ${gitErrorMessage(err)}`, "Ensure workspaceRoot is a git repository with at least one commit, and the worktree path is writable.", true, {
-            goal_id: goalId,
-            subgoal_id: subgoalId,
-            branch,
-            worktree_path: worktreePath,
-        });
-    }
+    });
 }
 /**
  * 读取 worktree_status.json。不存在返回 null。
@@ -183,13 +256,14 @@ export function readWorktreeStatus(worktreeId, workspaceRoot) {
     const statusFilePath = join(worktreePath, "worktree_status.json");
     if (!existsSync(statusFilePath))
         return null;
+    let parsed;
     try {
-        const raw = readFileSync(statusFilePath, "utf-8");
-        return JSON.parse(raw);
+        parsed = JSON.parse(readFileSync(statusFilePath, "utf-8"));
     }
     catch {
-        return null;
+        return invalidWorktreeStatus(worktreeId, "file is not valid JSON");
     }
+    return validateWorktreeStatus(parsed, worktreeId, wsRoot, worktreePath);
 }
 /**
  * 将 worktree 的 branch 合并回主工作区（workspaceRoot）。
@@ -203,32 +277,34 @@ export function readWorktreeStatus(worktreeId, workspaceRoot) {
  * （保留供人工排查冲突）。
  */
 export function mergeWorktree(worktreeId, workspaceRoot) {
-    const wsRoot = resolveWorkspaceRoot(workspaceRoot);
-    const worktreePath = getWorktreeDir(worktreeId, workspaceRoot);
-    guardWorkspacePath(worktreePath, wsRoot);
-    guardSensitivePath(worktreePath);
-    const status = readWorktreeStatus(worktreeId, workspaceRoot);
-    if (!status) {
-        throw new PatchWardenError("worktree_not_found", `Worktree "${worktreeId}" not found or has no worktree_status.json`, "Ensure the worktree id was created via createWorktree before merging.", true, { worktree_id: worktreeId });
-    }
-    if (status.status !== "active") {
-        throw new PatchWardenError("invalid_worktree_state", `Worktree "${worktreeId}" is not active (current status: "${status.status}")`, "Only active worktrees can be merged.", true, { worktree_id: worktreeId, current_status: status.status });
-    }
-    try {
-        runGit(["merge", status.branch], wsRoot, GIT_TIMEOUT_MS);
-    }
-    catch (err) {
-        // 合并失败：不删 worktree，保留供人工排查
-        throw new PatchWardenError("worktree_merge_failed", `Failed to merge worktree branch "${status.branch}" into workspace: ${gitErrorMessage(err)}`, "Resolve merge conflicts manually in the main workspace, then retry or discard the worktree.", true, { worktree_id: worktreeId, branch: status.branch });
-    }
-    const updatedStatus = {
-        ...status,
-        status: "merged",
-        merged_at: new Date().toISOString(),
-    };
-    const statusFilePath = join(worktreePath, "worktree_status.json");
-    writeStatusAtomic(statusFilePath, updatedStatus);
-    return { status: "merged" };
+    return withWorktreeRepositoryLock(workspaceRoot, () => {
+        const wsRoot = resolveWorkspaceRoot(workspaceRoot);
+        const worktreePath = getWorktreeDir(worktreeId, workspaceRoot);
+        guardWorkspacePath(worktreePath, wsRoot);
+        guardSensitivePath(worktreePath);
+        const status = readWorktreeStatus(worktreeId, workspaceRoot);
+        if (!status) {
+            throw new PatchWardenError("worktree_not_found", `Worktree "${worktreeId}" not found or has no worktree_status.json`, "Ensure the worktree id was created via createWorktree before merging.", true, { worktree_id: worktreeId });
+        }
+        if (status.status !== "active") {
+            throw new PatchWardenError("invalid_worktree_state", `Worktree "${worktreeId}" is not active (current status: "${status.status}")`, "Only active worktrees can be merged.", true, { worktree_id: worktreeId, current_status: status.status });
+        }
+        try {
+            runGit(["merge", status.branch], wsRoot, GIT_TIMEOUT_MS);
+        }
+        catch (err) {
+            // 合并失败：不删 worktree，保留供人工排查
+            throw new PatchWardenError("worktree_merge_failed", `Failed to merge worktree branch "${status.branch}" into workspace: ${gitErrorMessage(err)}`, "Resolve merge conflicts manually in the main workspace, then retry or discard the worktree.", true, { worktree_id: worktreeId, branch: status.branch });
+        }
+        const updatedStatus = {
+            ...status,
+            status: "merged",
+            merged_at: new Date().toISOString(),
+        };
+        const statusFilePath = join(worktreePath, "worktree_status.json");
+        writeStatusAtomic(statusFilePath, updatedStatus);
+        return { status: "merged" };
+    });
 }
 /**
  * 丢弃 worktree：移除 worktree 目录与临时 branch，归档最终状态。
@@ -245,48 +321,45 @@ export function mergeWorktree(worktreeId, workspaceRoot) {
  * 移除失败抛 PatchWardenError("worktree_discard_failed")。
  */
 export function discardWorktree(worktreeId, workspaceRoot) {
-    const wsRoot = resolveWorkspaceRoot(workspaceRoot);
-    const worktreePath = getWorktreeDir(worktreeId, workspaceRoot);
-    guardWorkspacePath(worktreePath, wsRoot);
-    guardSensitivePath(worktreePath);
-    // 在 remove 之前读取 status（status 文件位于 worktree 目录内）
-    const status = readWorktreeStatus(worktreeId, workspaceRoot);
-    if (!status) {
-        throw new PatchWardenError("worktree_not_found", `Worktree "${worktreeId}" not found or has no worktree_status.json`, "Ensure the worktree id was created via createWorktree before discarding.", true, { worktree_id: worktreeId });
-    }
-    if (status.status !== "active") {
-        throw new PatchWardenError("invalid_worktree_state", `Worktree "${worktreeId}" is not active (current status: "${status.status}")`, "Only active worktrees can be discarded.", true, { worktree_id: worktreeId, current_status: status.status });
-    }
-    try {
-        runGit(["worktree", "remove", "--force", worktreePath], wsRoot, GIT_TIMEOUT_MS);
-    }
-    catch (err) {
-        // git remove 失败时再尝试直接删目录（best effort），然后抛错
+    return withWorktreeRepositoryLock(workspaceRoot, () => {
+        const wsRoot = resolveWorkspaceRoot(workspaceRoot);
+        const worktreePath = getWorktreeDir(worktreeId, workspaceRoot);
+        guardWorkspacePath(worktreePath, wsRoot);
+        guardSensitivePath(worktreePath);
+        // 在 remove 之前读取 status（status 文件位于 worktree 目录内）
+        const status = readWorktreeStatus(worktreeId, workspaceRoot);
+        if (!status) {
+            throw new PatchWardenError("worktree_not_found", `Worktree "${worktreeId}" not found or has no worktree_status.json`, "Ensure the worktree id was created via createWorktree before discarding.", true, { worktree_id: worktreeId });
+        }
+        if (status.status !== "active") {
+            throw new PatchWardenError("invalid_worktree_state", `Worktree "${worktreeId}" is not active (current status: "${status.status}")`, "Only active worktrees can be discarded.", true, { worktree_id: worktreeId, current_status: status.status });
+        }
         try {
-            rmSync(worktreePath, { recursive: true, force: true });
+            runGit(["worktree", "remove", "--force", worktreePath], wsRoot, GIT_TIMEOUT_MS);
+        }
+        catch (err) {
+            throw new PatchWardenError("worktree_discard_failed", `Failed to remove worktree "${worktreeId}": ${gitErrorMessage(err)}`, "Remove the worktree directory manually and run `git worktree prune`.", true, { worktree_id: worktreeId, worktree_path: worktreePath });
+        }
+        // 删除临时 branch（best effort — 可能已随 worktree remove 清理）
+        try {
+            runGit(["branch", "-D", status.branch], wsRoot, GIT_BRANCH_TIMEOUT_MS);
         }
         catch { /* ignore */ }
-        throw new PatchWardenError("worktree_discard_failed", `Failed to remove worktree "${worktreeId}": ${gitErrorMessage(err)}`, "Remove the worktree directory manually and run `git worktree prune`.", true, { worktree_id: worktreeId, worktree_path: worktreePath });
-    }
-    // 删除临时 branch（best effort — 可能已随 worktree remove 清理）
-    try {
-        runGit(["branch", "-D", status.branch], wsRoot, GIT_BRANCH_TIMEOUT_MS);
-    }
-    catch { /* ignore */ }
-    // 归档最终状态到 .patchwarden/worktree-archive/（worktree 目录可能已消失）
-    const archivedStatus = {
-        ...status,
-        status: "discarded",
-        discarded_at: new Date().toISOString(),
-    };
-    const archiveDir = join(wsRoot, WORKTREE_ARCHIVE_DIR);
-    guardWorkspacePath(archiveDir, wsRoot);
-    // .patchwarden 路径在 sensitiveGuard 中始终视为安全（SAFE_PREFIX），无需额外校验
-    try {
-        mkdirSync(archiveDir, { recursive: true });
-    }
-    catch { /* ignore */ }
-    const archiveFilePath = join(archiveDir, `${worktreeId}.json`);
-    writeStatusAtomic(archiveFilePath, archivedStatus);
-    return { status: "discarded" };
+        // 归档最终状态到 .patchwarden/worktree-archive/（worktree 目录可能已消失）
+        const archivedStatus = {
+            ...status,
+            status: "discarded",
+            discarded_at: new Date().toISOString(),
+        };
+        const archiveDir = join(wsRoot, WORKTREE_ARCHIVE_DIR);
+        guardWorkspacePath(archiveDir, wsRoot);
+        // The archive path is workspace-confined and contains only managed status metadata.
+        try {
+            mkdirSync(archiveDir, { recursive: true });
+        }
+        catch { /* ignore */ }
+        const archiveFilePath = join(archiveDir, `${worktreeId}.json`);
+        writeStatusAtomic(archiveFilePath, archivedStatus);
+        return { status: "discarded" };
+    });
 }