patchwarden 1.5.1 → 1.6.2

package/dist/goal/acceptanceEngine.d.ts

@@ -12,7 +12,7 @@
  *   3. 存在 warn 级检查项或文档不同步 → NEEDS_FIX
  *   4. 所有检查通过 → ACCEPTED
  */
-import type { AcceptanceStatus } from "../tools/createTask.js";
+import type { AcceptanceStatus } from "../tools/tasks/createTask.js";
 export type AcceptanceVerdict = "ACCEPTED" | "NEEDS_FIX" | "REJECTED" | "BLOCKED_BY_APPROVAL";
 export interface AcceptanceCheck {
     name: string;

package/dist/goal/goalProgress.js

@@ -14,7 +14,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
 import { getConfig } from "../config.js";
 import { PatchWardenError } from "../errors.js";
-import { readGoalStatus, writeGoalStatus } from "./goalStore.js";
+import { mutateGoalStatus, readGoalStatus } from "./goalStore.js";
 import { updateSubgoalStatus } from "./goalStatus.js";
 import { getBlockedSubgoals } from "./goalGraph.js";
 // ── 辅助：解析 workspaceRoot ──────────────────────────────────────
@@ -66,42 +66,45 @@ function readTaskStatus(taskId, workspaceRoot) {
  * @throws {PatchWardenError} reason="goal_not_found" | "subgoal_not_found" | "subgoal_not_ready" | "invalid_status_transition"
  */
 export function acceptSubgoal(goalId, subgoalId, workspaceRoot) {
-    const goalStatus = readGoalStatus(goalId, workspaceRoot);
-    const subgoal = goalStatus.subgoals.find((s) => s.id === subgoalId);
-    if (!subgoal) {
-        throw new PatchWardenError("subgoal_not_found", `Subgoal "${subgoalId}" not found in goal "${goalId}"`, "Ensure the subgoal id exists before accepting.", true, { subgoal_id: subgoalId, goal_id: goalId });
-    }
-    // 校验 1：task_ids 不能为空
-    if (subgoal.task_ids.length === 0) {
-        throw new PatchWardenError("subgoal_not_ready", `Subgoal "${subgoalId}" has no associated tasks; cannot accept without task verification.`, "Link tasks to the subgoal and run audit_task on each before accepting.", true, { subgoal_id: subgoalId, goal_id: goalId, task_ids: [] });
-    }
-    // 校验 2：所有 task 必须为 accepted
-    const unacceptedTasks = [];
-    for (const taskId of subgoal.task_ids) {
-        const taskStatus = readTaskStatus(taskId, workspaceRoot);
-        if (taskStatus !== "accepted") {
-            unacceptedTasks.push({
-                task_id: taskId,
-                current_status: taskStatus ?? "missing",
+    return mutateGoalStatus(goalId, (goalStatus) => {
+        const subgoal = goalStatus.subgoals.find((s) => s.id === subgoalId);
+        if (!subgoal) {
+            throw new PatchWardenError("subgoal_not_found", `Subgoal "${subgoalId}" not found in goal "${goalId}"`, "Ensure the subgoal id exists before accepting.", true, { subgoal_id: subgoalId, goal_id: goalId });
+        }
+        // 校验 1：task_ids 不能为空
+        if (subgoal.task_ids.length === 0) {
+            throw new PatchWardenError("subgoal_not_ready", `Subgoal "${subgoalId}" has no associated tasks; cannot accept without task verification.`, "Link tasks to the subgoal and run audit_task on each before accepting.", true, { subgoal_id: subgoalId, goal_id: goalId, task_ids: [] });
+        }
+        // 校验 2：所有 task 必须为 accepted
+        const unacceptedTasks = [];
+        for (const taskId of subgoal.task_ids) {
+            const taskStatus = readTaskStatus(taskId, workspaceRoot);
+            if (taskStatus !== "accepted") {
+                unacceptedTasks.push({
+                    task_id: taskId,
+                    current_status: taskStatus ?? "missing",
+                });
+            }
+        }
+        if (unacceptedTasks.length > 0) {
+            throw new PatchWardenError("subgoal_not_ready", `Subgoal "${subgoalId}" cannot be accepted: ${unacceptedTasks.length} task(s) are not in "accepted" status.`, "Run audit_task on each unaccepted task first.", true, {
+                subgoal_id: subgoalId,
+                goal_id: goalId,
+                unaccepted_tasks: unacceptedTasks,
             });
         }
-    }
-    if (unacceptedTasks.length > 0) {
-        throw new PatchWardenError("subgoal_not_ready", `Subgoal "${subgoalId}" cannot be accepted: ${unacceptedTasks.length} task(s) are not in "accepted" status.`, "Run audit_task on each unaccepted task first.", true, {
-            subgoal_id: subgoalId,
-            goal_id: goalId,
-            unaccepted_tasks: unacceptedTasks,
-        });
-    }
-    // 校验 3：通过状态机转换（要求 subgoal 当前为 done_by_agent）
-    const updatedGoalStatus = updateSubgoalStatus(goalStatus, subgoalId, "accepted");
-    writeGoalStatus(goalId, updatedGoalStatus, workspaceRoot);
-    const updatedSubgoal = updatedGoalStatus.subgoals.find((s) => s.id === subgoalId);
-    return {
-        subgoal_id: subgoalId,
-        status: "accepted",
-        accepted_at: updatedSubgoal.accepted_at,
-    };
+        // 校验 3：通过状态机转换（要求 subgoal 当前为 done_by_agent）
+        const updatedGoalStatus = updateSubgoalStatus(goalStatus, subgoalId, "accepted");
+        const updatedSubgoal = updatedGoalStatus.subgoals.find((s) => s.id === subgoalId);
+        return {
+            next: updatedGoalStatus,
+            result: {
+                subgoal_id: subgoalId,
+                status: "accepted",
+                accepted_at: updatedSubgoal.accepted_at,
+            },
+        };
+    }, workspaceRoot);
 }
 /**
  * 拒绝子目标：从任意非终态（ready/running/done_by_agent/needs_fix）拒绝 subgoal。
@@ -117,40 +120,43 @@ export function acceptSubgoal(goalId, subgoalId, workspaceRoot) {
  * @throws {PatchWardenError} reason="goal_not_found" | "subgoal_not_found" | "invalid_status_transition"
  */
 export function rejectSubgoal(goalId, subgoalId, reason, workspaceRoot) {
-    const goalStatus = readGoalStatus(goalId, workspaceRoot);
-    const index = goalStatus.subgoals.findIndex((s) => s.id === subgoalId);
-    if (index === -1) {
-        throw new PatchWardenError("subgoal_not_found", `Subgoal "${subgoalId}" not found in goal "${goalId}"`, "Ensure the subgoal id exists before rejecting.", true, { subgoal_id: subgoalId, goal_id: goalId });
-    }
-    const current = goalStatus.subgoals[index];
-    // 终态检查：accepted 和 rejected 不允许再 reject
-    if (current.status === "accepted" || current.status === "rejected") {
-        throw new PatchWardenError("invalid_status_transition", `Cannot reject subgoal "${subgoalId}" in terminal state "${current.status}".`, "Reject is only allowed from non-terminal states (ready, running, done_by_agent, needs_fix).", true, {
-            subgoal_id: subgoalId,
-            goal_id: goalId,
-            from_status: current.status,
-            to_status: "rejected",
-        });
-    }
-    // 手动更新 status 和 rejected_reason（绕过状态机）
-    const updatedSubgoal = {
-        ...current,
-        status: "rejected",
-        rejected_reason: reason,
-    };
-    const newSubgoals = [...goalStatus.subgoals];
-    newSubgoals[index] = updatedSubgoal;
-    const updatedGoalStatus = {
-        ...goalStatus,
-        subgoals: newSubgoals,
-        updated_at: new Date().toISOString(),
-    };
-    writeGoalStatus(goalId, updatedGoalStatus, workspaceRoot);
-    return {
-        subgoal_id: subgoalId,
-        status: "rejected",
-        rejected_reason: reason,
-    };
+    return mutateGoalStatus(goalId, (goalStatus) => {
+        const index = goalStatus.subgoals.findIndex((s) => s.id === subgoalId);
+        if (index === -1) {
+            throw new PatchWardenError("subgoal_not_found", `Subgoal "${subgoalId}" not found in goal "${goalId}"`, "Ensure the subgoal id exists before rejecting.", true, { subgoal_id: subgoalId, goal_id: goalId });
+        }
+        const current = goalStatus.subgoals[index];
+        // 终态检查：accepted 和 rejected 不允许再 reject
+        if (current.status === "accepted" || current.status === "rejected") {
+            throw new PatchWardenError("invalid_status_transition", `Cannot reject subgoal "${subgoalId}" in terminal state "${current.status}".`, "Reject is only allowed from non-terminal states (ready, running, done_by_agent, needs_fix).", true, {
+                subgoal_id: subgoalId,
+                goal_id: goalId,
+                from_status: current.status,
+                to_status: "rejected",
+            });
+        }
+        // 手动更新 status 和 rejected_reason（绕过状态机）
+        const updatedSubgoal = {
+            ...current,
+            status: "rejected",
+            rejected_reason: reason,
+        };
+        const newSubgoals = [...goalStatus.subgoals];
+        newSubgoals[index] = updatedSubgoal;
+        const updatedGoalStatus = {
+            ...goalStatus,
+            subgoals: newSubgoals,
+            updated_at: new Date().toISOString(),
+        };
+        return {
+            next: updatedGoalStatus,
+            result: {
+                subgoal_id: subgoalId,
+                status: "rejected",
+                rejected_reason: reason,
+            },
+        };
+    }, workspaceRoot);
 }
 /**
  * 汇总 Goal 进度：统计各状态数量、完成率、阻塞子目标、风险项。

package/dist/goal/goalReport.js

@@ -5,25 +5,18 @@
  * 生成 REPORT.md 和 report.json 到 {workspaceRoot}/.patchwarden/goals/{goalId}/report/。
  * 所有写入操作使用原子写（.tmp + rename），所有字符串内容经 redactSensitiveValue 脱敏。
  */
-import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { mkdirSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { getConfig } from "../config.js";
 import { redactSensitiveValue } from "../security/contentRedaction.js";
-import { listEvidencePacks } from "../tools/evidencePack.js";
+import { listEvidencePacks } from "../tools/tasks/evidencePack.js";
+import { atomicWriteFileSync } from "../utils/atomicFile.js";
 import { summarizeGoalProgress } from "./goalProgress.js";
 import { readGoalStatus } from "./goalStore.js";
 // ── 辅助函数 ──────────────────────────────────────────────────────
 function resolveWorkspaceRoot(workspaceRoot) {
     return workspaceRoot ?? getConfig().workspaceRoot;
 }
-/**
- * 原子写文件：先写到 .tmp 文件，再 renameSync 到目标路径。
- */
-function atomicWriteFile(filePath, content) {
-    const tmpPath = filePath + ".tmp";
-    writeFileSync(tmpPath, content, "utf-8");
-    renameSync(tmpPath, filePath);
-}
 /**
  * 将百分比字符串（如 "100%"）解析为数字。
  */
@@ -196,9 +189,9 @@ export function exportGoalReport(goalId, options) {
     // 脱敏所有字符串内容
     const safeReport = redactSensitiveValue(rawReport).value;
     // 原子写 JSON（机器可读）
-    atomicWriteFile(reportJsonPath, JSON.stringify(safeReport, null, 2) + "\n");
+    atomicWriteFileSync(reportJsonPath, JSON.stringify(safeReport, null, 2) + "\n");
     // 原子写 Markdown（人类可读，从脱敏后的对象生成）
     const markdown = buildReportMarkdown(safeReport, { noSubgoals, incomplete });
-    atomicWriteFile(reportMdPath, markdown);
+    atomicWriteFileSync(reportMdPath, markdown);
     return safeReport;
 }

package/dist/goal/goalStatus.d.ts

@@ -23,6 +23,8 @@ export interface Subgoal {
     external_ref?: string;
     /** Spec Kit task.files 提示（作用域文件路径列表） */
     scope_hints?: string[];
+    /** Managed git worktree associated with an isolated subgoal task. */
+    worktree_id?: string;
 }
 export interface GoalStatus {
     goal_id: string;

package/dist/goal/goalStatus.js

@@ -11,6 +11,7 @@
  * 所有更新函数返回新的 GoalStatus 对象，不修改原对象。
  */
 import { PatchWardenError } from "../errors.js";
+import { redactSensitiveContent } from "../security/contentRedaction.js";
 // ── 合法状态转换表 ────────────────────────────────────────────────
 const LEGAL_TRANSITIONS = {
     ready: ["running"],
@@ -29,7 +30,7 @@ export function createInitialGoalStatus(goalId, title, repoPath) {
     const now = new Date().toISOString();
     return {
         goal_id: goalId,
-        title,
+        title: redactGoalText(title, 500),
         status: "active",
         repo_path: repoPath,
         created_at: now,
@@ -44,6 +45,9 @@ export function createInitialGoalStatus(goalId, title, repoPath) {
  * 不可变更新：返回新的 GoalStatus 对象。
  */
 export function addSubgoal(goalStatus, title, dependsOn = []) {
+    if (goalStatus.status !== "active") {
+        throw new PatchWardenError("goal_not_active", `Goal "${goalStatus.goal_id}" is ${goalStatus.status} and cannot accept new subgoals.`, "Create a new Goal Session for additional work.", true, { goal_id: goalStatus.goal_id, status: goalStatus.status });
+    }
     const existingIds = new Set(goalStatus.subgoals.map((s) => s.id));
     for (const depId of dependsOn) {
         if (!existingIds.has(depId)) {
@@ -54,7 +58,7 @@ export function addSubgoal(goalStatus, title, dependsOn = []) {
     const subgoalId = `subgoal-${String(nextNumber).padStart(3, "0")}`;
     const newSubgoal = {
         id: subgoalId,
-        title,
+        title: redactGoalText(title, 500),
         status: "ready",
         depends_on: [...dependsOn],
         task_ids: [],
@@ -99,7 +103,7 @@ export function updateSubgoalStatus(goalStatus, subgoalId, newStatus, options) {
         if (!options || !options.rejected_reason) {
             throw new PatchWardenError("invalid_status_transition", `Rejecting subgoal "${subgoalId}" requires rejected_reason`, "Provide options.rejected_reason when transitioning to \"rejected\".", true, { subgoal_id: subgoalId, from_status: current.status, to_status: newStatus });
         }
-        updatedSubgoal.rejected_reason = options.rejected_reason;
+        updatedSubgoal.rejected_reason = redactGoalText(options.rejected_reason, 2000);
     }
     const newSubgoals = [...goalStatus.subgoals];
     newSubgoals[index] = updatedSubgoal;
@@ -109,6 +113,9 @@ export function updateSubgoalStatus(goalStatus, subgoalId, newStatus, options) {
         updated_at: new Date().toISOString(),
     };
 }
+function redactGoalText(value, maxChars) {
+    return redactSensitiveContent(String(value || "")).content.slice(0, maxChars);
+}
 /**
  * 将 taskId 关联到指定 subgoal（去重）。
  * 不可变更新：返回新的 GoalStatus 对象。

package/dist/goal/goalStore.d.ts

@@ -13,6 +13,8 @@
  * 默认从 getConfig().workspaceRoot 读取。
  */
 import { type GoalStatus, type Subgoal } from "./goalStatus.js";
+/** Validate the storage key before it can participate in path construction. */
+export declare function assertValidGoalId(goalId: string): void;
 /**
  * 生成 `goal_{YYYYMMDD}_{slug}` 格式的 goal id。
  * 冲突时追加 `_2`、`_3`... 直到唯一。
@@ -68,8 +70,7 @@ export declare function readGoal(goalId: string, workspaceRoot?: string): {
     subgoals: Subgoal[];
 };
 /**
- * 原子写入 goal_status.json：先写到 .tmp 文件，再 renameSync。
- * JSON 序列化用 JSON.stringify(status, null, 2) + 末尾换行。
+ * Replace goal_status.json under the shared cross-process mutation lock.
  */
 export declare function writeGoalStatus(goalId: string, status: GoalStatus, workspaceRoot?: string): void;
 /**
@@ -77,3 +78,9 @@ export declare function writeGoalStatus(goalId: string, status: GoalStatus, work
  * 如果文件不存在，抛出 PatchWardenError("goal_not_found")。
  */
 export declare function readGoalStatus(goalId: string, workspaceRoot?: string): GoalStatus;
+export interface GoalStatusMutation<R> {
+    next?: GoalStatus;
+    result: R;
+}
+export declare function mutateGoalStatus<R>(goalId: string, mutation: (current: GoalStatus) => GoalStatusMutation<R>, workspaceRoot?: string): R;
+export declare function mutateGoalStatusAsync<R>(goalId: string, mutation: (current: GoalStatus) => Promise<GoalStatusMutation<R>>, workspaceRoot?: string): Promise<R>;

package/dist/goal/goalStore.js

@@ -12,16 +12,29 @@
  * 所有文件系统函数都接受可选的 workspaceRoot 参数用于测试；
  * 默认从 getConfig().workspaceRoot 读取。
  */
-import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync, statSync, } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, } from "node:fs";
 import { join } from "node:path";
 import { getConfig } from "../config.js";
-import { guardWorkspacePath } from "../security/pathGuard.js";
+import { guardPath, guardWorkspacePath } from "../security/pathGuard.js";
 import { PatchWardenError } from "../errors.js";
+import { atomicWriteFileSync, atomicWriteJsonFileSync } from "../utils/atomicFile.js";
+import { redactSensitiveContent } from "../security/contentRedaction.js";
+import { mutateLockedJsonFileSync, readJsonObjectFileSync, withFileLock, withFileLockSync, } from "../utils/lockedJsonFile.js";
 import { createInitialGoalStatus, } from "./goalStatus.js";
 // ── 辅助：解析 workspaceRoot ──────────────────────────────────────
 function resolveWorkspaceRoot(workspaceRoot) {
     return workspaceRoot ?? getConfig().workspaceRoot;
 }
+const GOALS_PREFIX = join(".patchwarden", "goals");
+const GOAL_ID_MAX_LENGTH = 128;
+const GOAL_ID_PATTERN = /^goal_[A-Za-z0-9][A-Za-z0-9_-]*$/;
+/** Validate the storage key before it can participate in path construction. */
+export function assertValidGoalId(goalId) {
+    if (goalId.length > GOAL_ID_MAX_LENGTH ||
+        !GOAL_ID_PATTERN.test(goalId)) {
+        throw new PatchWardenError("invalid_goal_id", `Invalid goal id. Expected "goal_" followed by at most ${GOAL_ID_MAX_LENGTH - 5} ASCII letters, digits, underscores, or hyphens.`, "Use the goal_id returned by create_goal or list_goals.", true, { goal_id_length: goalId.length });
+    }
+}
 // ── Goal ID 生成 ──────────────────────────────────────────────────
 /**
  * 从 title 生成 slug：小写、非字母数字字符替换为 `_`、合并连续 `_`、去除首尾 `_`、截断到 30 字符。
@@ -64,13 +77,16 @@ export function generateGoalId(title, existingIds) {
  * 不自动创建目录。
  */
 export function getGoalsDir(workspaceRoot) {
-    return join(resolveWorkspaceRoot(workspaceRoot), ".patchwarden", "goals");
+    const wsRoot = resolveWorkspaceRoot(workspaceRoot);
+    return guardPath(join(wsRoot, GOALS_PREFIX), wsRoot, GOALS_PREFIX);
 }
 /**
  * 返回 `{getGoalsDir()}/{goalId}` 路径。
  */
 export function getGoalDir(goalId, workspaceRoot) {
-    return join(getGoalsDir(workspaceRoot), goalId);
+    assertValidGoalId(goalId);
+    const wsRoot = resolveWorkspaceRoot(workspaceRoot);
+    return guardPath(join(getGoalsDir(wsRoot), goalId), wsRoot, GOALS_PREFIX);
 }
 // ── CRUD ──────────────────────────────────────────────────────────
 /**
@@ -82,11 +98,21 @@ export function getGoalDir(goalId, workspaceRoot) {
  * 返回 { goal_id, goal_dir }。
  */
 export function createGoal(repoPath, title, description, workspaceRoot) {
+    const safeTitle = redactSensitiveContent(title)
+        .content
+        .replace(/[\r\n\t]+/g, " ")
+        .trim()
+        .slice(0, 500) || "Untitled goal";
+    const safeDescription = redactSensitiveContent(description).content;
+    if (Buffer.byteLength(safeDescription, "utf-8") > 1024 * 1024) {
+        throw new PatchWardenError("goal_description_too_large", "Goal description exceeds the 1 MiB limit.", "Split the work into smaller Goal Sessions.");
+    }
     const wsRoot = resolveWorkspaceRoot(workspaceRoot);
     const guardedRepo = guardWorkspacePath(repoPath, wsRoot);
     const goalsDir = getGoalsDir(workspaceRoot);
-    const existingIds = [];
-    if (existsSync(goalsDir)) {
+    mkdirSync(goalsDir, { recursive: true });
+    return withFileLockSync(join(goalsDir, "goal-creation"), () => {
+        const existingIds = [];
         for (const entry of readdirSync(goalsDir)) {
             const entryPath = join(goalsDir, entry);
             try {
@@ -95,35 +121,32 @@ export function createGoal(repoPath, title, description, workspaceRoot) {
                 }
             }
             catch {
-                // 跳过无法 stat 的条目
+                // Skip entries that cannot be inspected.
             }
         }
-    }
-    const goalId = generateGoalId(title, existingIds);
-    const goalDir = join(goalsDir, goalId);
-    // 创建目录结构
-    mkdirSync(join(goalDir, "tasks"), { recursive: true });
-    mkdirSync(join(goalDir, "artifacts"), { recursive: true });
-    // 写入 GOAL.md
-    const now = new Date().toISOString();
-    const goalMd = [
-        `# ${title}`,
-        "",
-        description,
-        "",
-        `- Created: ${now}`,
-        `- Repo: ${guardedRepo}`,
-        "- Status: active",
-        "",
-    ].join("\n");
-    writeFileSync(join(goalDir, "GOAL.md"), goalMd, "utf-8");
-    // 写入 GOALS.md
-    const goalsMd = `# Subgoals: ${title}\n\n_No subgoals yet._\n`;
-    writeFileSync(join(goalDir, "GOALS.md"), goalsMd, "utf-8");
-    // 写入 goal_status.json
-    const status = createInitialGoalStatus(goalId, title, guardedRepo);
-    writeFileSync(join(goalDir, "goal_status.json"), JSON.stringify(status, null, 2) + "\n", "utf-8");
-    return { goal_id: goalId, goal_dir: goalDir };
+        const goalId = generateGoalId(safeTitle, existingIds);
+        const goalDir = getGoalDir(goalId, wsRoot);
+        mkdirSync(goalDir);
+        mkdirSync(join(goalDir, "tasks"));
+        mkdirSync(join(goalDir, "artifacts"));
+        const now = new Date().toISOString();
+        const goalMd = [
+            `# ${safeTitle}`,
+            "",
+            safeDescription,
+            "",
+            `- Created: ${now}`,
+            `- Repo: ${guardedRepo}`,
+            "- Status: active",
+            "",
+        ].join("\n");
+        atomicWriteFileSync(join(goalDir, "GOAL.md"), goalMd);
+        const goalsMd = `# Subgoals: ${safeTitle}\n\n_No subgoals yet._\n`;
+        atomicWriteFileSync(join(goalDir, "GOALS.md"), goalsMd);
+        const status = createInitialGoalStatus(goalId, safeTitle, guardedRepo);
+        atomicWriteJsonFileSync(join(goalDir, "goal_status.json"), status);
+        return { goal_id: goalId, goal_dir: goalDir };
+    }, goalBusyOptions("creation"));
 }
 /**
  * 列出所有 goal 的摘要信息，按 updated_at 降序排列。
@@ -136,8 +159,8 @@ export function listGoals(workspaceRoot) {
     }
     const results = [];
     for (const entry of readdirSync(goalsDir)) {
-        const entryPath = join(goalsDir, entry);
         try {
+            const entryPath = getGoalDir(entry, workspaceRoot);
             if (!statSync(entryPath).isDirectory()) {
                 continue;
             }
@@ -172,7 +195,8 @@ export function readGoal(goalId, workspaceRoot) {
     let goalDescription = "";
     const goalMdPath = join(goalDir, "GOAL.md");
     if (existsSync(goalMdPath)) {
-        goalDescription = readFileSync(goalMdPath, "utf-8");
+        const safeGoalMdPath = guardPath(goalMdPath, resolveWorkspaceRoot(workspaceRoot), GOALS_PREFIX);
+        goalDescription = readFileSync(safeGoalMdPath, "utf-8");
     }
     return {
         goal_id: status.goal_id,
@@ -186,26 +210,109 @@ export function readGoal(goalId, workspaceRoot) {
     };
 }
 /**
- * 原子写入 goal_status.json：先写到 .tmp 文件，再 renameSync。
- * JSON 序列化用 JSON.stringify(status, null, 2) + 末尾换行。
+ * Replace goal_status.json under the shared cross-process mutation lock.
  */
 export function writeGoalStatus(goalId, status, workspaceRoot) {
     const goalDir = getGoalDir(goalId, workspaceRoot);
-    const finalPath = join(goalDir, "goal_status.json");
-    const tmpPath = join(goalDir, "goal_status.json.tmp");
-    writeFileSync(tmpPath, JSON.stringify(status, null, 2) + "\n", "utf-8");
-    renameSync(tmpPath, finalPath);
+    if (!existsSync(goalDir)) {
+        throw new PatchWardenError("goal_not_found", `Goal directory not found: "${goalDir}"`, "Ensure the goal has been created before writing its status.", true, { goal_id: goalId, goal_dir: goalDir });
+    }
+    const statusPath = getGoalStatusPath(goalId, workspaceRoot);
+    if (!existsSync(statusPath)) {
+        withFileLockSync(statusPath, () => {
+            atomicWriteJsonFileSync(statusPath, normalizeGoalLifecycle(validateGoalStatus(goalId, status, workspaceRoot)));
+        }, goalBusyOptions(goalId));
+        return;
+    }
+    mutateGoalStatus(goalId, () => ({ next: status, result: undefined }), workspaceRoot);
 }
 /**
  * 读取 goal_status.json 并 JSON.parse。
  * 如果文件不存在，抛出 PatchWardenError("goal_not_found")。
  */
 export function readGoalStatus(goalId, workspaceRoot) {
-    const goalDir = getGoalDir(goalId, workspaceRoot);
-    const statusPath = join(goalDir, "goal_status.json");
+    const statusPath = getGoalStatusPath(goalId, workspaceRoot);
     if (!existsSync(statusPath)) {
         throw new PatchWardenError("goal_not_found", `goal_status.json not found for goal "${goalId}" at "${statusPath}"`, "Ensure the goal has been created via createGoal before reading its status.", true, { goal_id: goalId, status_path: statusPath });
     }
-    const raw = readFileSync(statusPath, "utf-8");
-    return JSON.parse(raw);
+    let parsed;
+    try {
+        parsed = readJsonObjectFileSync(statusPath);
+    }
+    catch {
+        throw invalidGoalStatus(goalId, "goal_status.json is not valid JSON");
+    }
+    return validateGoalStatus(goalId, parsed, workspaceRoot);
+}
+export function mutateGoalStatus(goalId, mutation, workspaceRoot) {
+    const statusPath = getGoalStatusPath(goalId, workspaceRoot);
+    ensureGoalStatusExists(goalId, statusPath);
+    return mutateLockedJsonFileSync(statusPath, (raw) => {
+        const current = validateGoalStatus(goalId, raw, workspaceRoot);
+        const outcome = mutation(current);
+        if (!outcome.next)
+            return outcome;
+        return {
+            next: normalizeGoalLifecycle(validateGoalStatus(goalId, outcome.next, workspaceRoot)),
+            result: outcome.result,
+        };
+    }, goalBusyOptions(goalId));
+}
+export async function mutateGoalStatusAsync(goalId, mutation, workspaceRoot) {
+    const statusPath = getGoalStatusPath(goalId, workspaceRoot);
+    ensureGoalStatusExists(goalId, statusPath);
+    return withFileLock(statusPath, async () => {
+        const current = validateGoalStatus(goalId, readJsonObjectFileSync(statusPath), workspaceRoot);
+        const outcome = await mutation(current);
+        if (outcome.next) {
+            atomicWriteJsonFileSync(statusPath, normalizeGoalLifecycle(validateGoalStatus(goalId, outcome.next, workspaceRoot)));
+        }
+        return outcome.result;
+    }, goalBusyOptions(goalId));
+}
+function getGoalStatusPath(goalId, workspaceRoot) {
+    const wsRoot = resolveWorkspaceRoot(workspaceRoot);
+    return guardPath(join(getGoalDir(goalId, wsRoot), "goal_status.json"), wsRoot, GOALS_PREFIX);
+}
+function ensureGoalStatusExists(goalId, statusPath) {
+    if (!existsSync(statusPath)) {
+        throw new PatchWardenError("goal_not_found", `goal_status.json not found for goal "${goalId}" at "${statusPath}"`, "Ensure the goal has been created via createGoal before updating it.", true, { goal_id: goalId, status_path: statusPath });
+    }
+}
+function validateGoalStatus(goalId, value, workspaceRoot) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw invalidGoalStatus(goalId, "expected a JSON object");
+    }
+    const candidate = value;
+    if (candidate.goal_id !== goalId) {
+        throw invalidGoalStatus(goalId, "goal_id does not match its directory");
+    }
+    if (typeof candidate.title !== "string" || typeof candidate.repo_path !== "string") {
+        throw invalidGoalStatus(goalId, "title or repo_path is missing");
+    }
+    if (candidate.status !== "active" && candidate.status !== "completed" && candidate.status !== "abandoned") {
+        throw invalidGoalStatus(goalId, "status is invalid");
+    }
+    if (!Array.isArray(candidate.subgoals)) {
+        throw invalidGoalStatus(goalId, "subgoals must be an array");
+    }
+    guardWorkspacePath(candidate.repo_path, resolveWorkspaceRoot(workspaceRoot));
+    return candidate;
+}
+function normalizeGoalLifecycle(status) {
+    if (status.status === "active" &&
+        status.subgoals.length > 0 &&
+        status.subgoals.every((subgoal) => subgoal.status === "accepted")) {
+        return { ...status, status: "completed", updated_at: new Date().toISOString() };
+    }
+    return status;
+}
+function invalidGoalStatus(goalId, detail) {
+    return new PatchWardenError("invalid_goal_status", `Invalid goal status for "${goalId}": ${detail}.`, "Recreate the Goal Session or restore a valid goal_status.json artifact.", true, { goal_id: goalId });
+}
+function goalBusyOptions(goalId) {
+    return {
+        waitMs: 0,
+        busyError: () => new PatchWardenError("goal_busy", `Goal "${goalId}" is currently being updated.`, "Retry after the active Goal operation finishes.", true, { goal_id: goalId }),
+    };
 }

package/dist/goal/handoffExport.js

@@ -7,9 +7,10 @@
  * 以避免与 goalStore 形成循环依赖。
  */
 import { suggestNextSubgoal } from "./goalGraph.js";
-import { getConfig } from "../config.js";
-import { mkdirSync, writeFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { getGoalDir } from "./goalStore.js";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteFileSync } from "../utils/atomicFile.js";
 // ── Markdown 生成 ────────────────────────────────────────────────
 /**
  * 生成 Goal Session 交接文档（Markdown 字符串）。
@@ -170,11 +171,10 @@ export function generateHandoff(goalId, goalStatus, recentDiff, recentTestResult
  */
 export function exportHandoff(goalId, goalStatus, workspaceRoot) {
     const content = generateHandoff(goalId, goalStatus);
-    const root = workspaceRoot ?? getConfig().workspaceRoot;
-    const goalDir = resolve(root, ".patchwarden", "goals", goalId);
+    const goalDir = getGoalDir(goalId, workspaceRoot);
     mkdirSync(goalDir, { recursive: true });
     const handoffPath = join(goalDir, "handoff.md");
-    writeFileSync(handoffPath, content, "utf-8");
+    atomicWriteFileSync(handoffPath, content);
     const preview = content.length > 500 ? content.slice(0, 500) + "..." : content;
     return {
         handoff_path: handoffPath,