patchwarden 1.5.0 → 1.6.1

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.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Goal 最终报告导出 — 将 Goal 完成情况渲染为人类可读 Markdown 和机器可读 JSON。
+ *
+ * exportGoalReport 读取 GoalStatus 和进度统计，关联 Evidence Pack，
+ * 生成 REPORT.md 和 report.json 到 {workspaceRoot}/.patchwarden/goals/{goalId}/report/。
+ * 所有写入操作使用原子写（.tmp + rename），所有字符串内容经 redactSensitiveValue 脱敏。
+ */
+import { type GoalProgressSummary } from "./goalProgress.js";
+export interface SubgoalReportEntry {
+    id: string;
+    title: string;
+    status: string;
+    task_ids: string[];
+    evidence_packs: string[];
+    accepted_at?: string;
+    rejected_reason?: string;
+}
+export interface SafeGoalReport {
+    goal_id: string;
+    generated_at: string;
+    path: string;
+    completion_rate: number;
+    files: {
+        report_md: string;
+        report_json: string;
+    };
+    summary: GoalProgressSummary;
+    subgoals: SubgoalReportEntry[];
+    risks: string[];
+    timeline: {
+        created_at: string;
+        updated_at: string;
+        status: string;
+    };
+    bounded: true;
+}
+/**
+ * 导出 Goal 最终报告，生成 REPORT.md 和 report.json。
+ *
+ * 流程：
+ *   1. 读取 GoalStatus（readGoalStatus）
+ *   2. 调用 summarizeGoalProgress 获取完成度统计
+ *   3. 遍历 subgoals，构建 SubgoalReportEntry，关联 Evidence Pack
+ *   4. 生成 REPORT.md（人类可读）和 report.json（机器可读）
+ *   5. 原子写到 {workspaceRoot}/.patchwarden/goals/{goalId}/report/
+ *   6. 所有字符串内容经 redactSensitiveValue 脱敏
+ *
+ * @param goalId   Goal 标识
+ * @param options  可选配置（workspaceRoot：工作区根目录，默认从 getConfig 获取）
+ * @returns SafeGoalReport（脱敏后的报告对象）
+ */
+export declare function exportGoalReport(goalId: string, options?: {
+    workspaceRoot?: string;
+}): SafeGoalReport;

package/dist/goal/goalReport.js

@@ -0,0 +1,197 @@
+/**
+ * Goal 最终报告导出 — 将 Goal 完成情况渲染为人类可读 Markdown 和机器可读 JSON。
+ *
+ * exportGoalReport 读取 GoalStatus 和进度统计，关联 Evidence Pack，
+ * 生成 REPORT.md 和 report.json 到 {workspaceRoot}/.patchwarden/goals/{goalId}/report/。
+ * 所有写入操作使用原子写（.tmp + rename），所有字符串内容经 redactSensitiveValue 脱敏。
+ */
+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/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;
+}
+/**
+ * 将百分比字符串（如 "100%"）解析为数字。
+ */
+function parseCompletionRate(value) {
+    const n = parseInt(value, 10);
+    return Number.isFinite(n) ? n : 0;
+}
+/**
+ * 查找与 task_ids 关联的 Evidence Pack 路径。
+ * 通过 listEvidencePacks 列出所有 pack，匹配 lineage_id 在 task_ids 中的 pack。
+ */
+function collectEvidencePacks(taskIds) {
+    if (taskIds.length === 0)
+        return [];
+    const packs = listEvidencePacks({ max_items: 50 });
+    const taskIdSet = new Set(taskIds);
+    const paths = [];
+    for (const pack of packs.evidence_packs) {
+        if (taskIdSet.has(pack.lineage_id)) {
+            paths.push(pack.path);
+        }
+    }
+    return paths;
+}
+// ── Markdown 生成 ─────────────────────────────────────────────────
+/**
+ * 从脱敏后的报告对象生成人类可读 Markdown。
+ */
+function buildReportMarkdown(report, flags) {
+    const lines = [];
+    // 标题
+    lines.push("# Goal Report: " + report.summary.title);
+    lines.push("");
+    // 元信息
+    lines.push("## 元信息");
+    lines.push("");
+    lines.push("- **goal_id**: " + report.goal_id);
+    lines.push("- **generated_at**: " + report.generated_at);
+    lines.push("- **status**: " + report.timeline.status);
+    lines.push("- **completion_rate**: " + report.completion_rate + "%");
+    if (flags.noSubgoals) {
+        lines.push("- **备注**: 无子目标");
+    }
+    if (flags.incomplete) {
+        lines.push("- **备注**: 未完成");
+    }
+    lines.push("");
+    // 完成度统计表
+    lines.push("## 完成度统计");
+    lines.push("");
+    lines.push("| 指标 | 数值 |");
+    lines.push("| --- | --- |");
+    lines.push("| total | " + report.summary.total + " |");
+    lines.push("| accepted | " + report.summary.accepted + " |");
+    lines.push("| rejected | " + report.summary.rejected + " |");
+    lines.push("| running | " + report.summary.running + " |");
+    lines.push("| ready | " + report.summary.ready + " |");
+    lines.push("| needs_fix | " + report.summary.needs_fix + " |");
+    lines.push("");
+    // 子目标清单
+    lines.push("## 子目标清单");
+    lines.push("");
+    if (report.subgoals.length === 0) {
+        lines.push("无子目标");
+        lines.push("");
+    }
+    else {
+        for (const sg of report.subgoals) {
+            lines.push("### " + sg.id + ": " + sg.title);
+            lines.push("");
+            lines.push("- **status**: " + sg.status);
+            lines.push("- **task_ids**: " + (sg.task_ids.length > 0 ? sg.task_ids.join(", ") : "无"));
+            lines.push("- **evidence_packs**: " +
+                (sg.evidence_packs.length > 0 ? sg.evidence_packs.join(", ") : "无"));
+            if (sg.accepted_at) {
+                lines.push("- **accepted_at**: " + sg.accepted_at);
+            }
+            if (sg.rejected_reason) {
+                lines.push("- **rejected_reason**: " + sg.rejected_reason);
+            }
+            lines.push("");
+        }
+    }
+    // 风险汇总
+    lines.push("## 风险汇总");
+    lines.push("");
+    if (report.risks.length === 0) {
+        lines.push("无");
+    }
+    else {
+        for (const r of report.risks) {
+            lines.push("- " + r);
+        }
+    }
+    lines.push("");
+    // 时间线
+    lines.push("## 时间线");
+    lines.push("");
+    lines.push("- **created_at**: " + report.timeline.created_at);
+    lines.push("- **updated_at**: " + report.timeline.updated_at);
+    lines.push("");
+    return lines.join("\n");
+}
+// ── 公共 API ──────────────────────────────────────────────────────
+/**
+ * 导出 Goal 最终报告，生成 REPORT.md 和 report.json。
+ *
+ * 流程：
+ *   1. 读取 GoalStatus（readGoalStatus）
+ *   2. 调用 summarizeGoalProgress 获取完成度统计
+ *   3. 遍历 subgoals，构建 SubgoalReportEntry，关联 Evidence Pack
+ *   4. 生成 REPORT.md（人类可读）和 report.json（机器可读）
+ *   5. 原子写到 {workspaceRoot}/.patchwarden/goals/{goalId}/report/
+ *   6. 所有字符串内容经 redactSensitiveValue 脱敏
+ *
+ * @param goalId   Goal 标识
+ * @param options  可选配置（workspaceRoot：工作区根目录，默认从 getConfig 获取）
+ * @returns SafeGoalReport（脱敏后的报告对象）
+ */
+export function exportGoalReport(goalId, options) {
+    const workspaceRoot = resolveWorkspaceRoot(options?.workspaceRoot);
+    const goalStatus = readGoalStatus(goalId, workspaceRoot);
+    const summary = summarizeGoalProgress(goalId, workspaceRoot);
+    const generatedAt = new Date().toISOString();
+    const noSubgoals = goalStatus.subgoals.length === 0;
+    const hasIncomplete = goalStatus.subgoals.some((s) => s.status === "running" || s.status === "ready");
+    const incomplete = goalStatus.status === "active" && hasIncomplete;
+    // 构建 subgoal 报告条目
+    const subgoalEntries = goalStatus.subgoals.map((sg) => {
+        const entry = {
+            id: sg.id,
+            title: sg.title,
+            status: sg.status,
+            task_ids: [...sg.task_ids],
+            evidence_packs: collectEvidencePacks(sg.task_ids),
+        };
+        if (sg.accepted_at)
+            entry.accepted_at = sg.accepted_at;
+        if (sg.rejected_reason)
+            entry.rejected_reason = sg.rejected_reason;
+        return entry;
+    });
+    // 风险汇总
+    const risks = summary.risks.map((r) => r.subgoal_id + " (" + r.status + "): " + r.reason);
+    if (incomplete) {
+        risks.push("未完成：Goal 仍有 running/ready 子目标");
+    }
+    // 报告目录
+    const reportDir = resolve(workspaceRoot, ".patchwarden", "goals", goalId, "report");
+    mkdirSync(reportDir, { recursive: true });
+    const reportMdPath = join(reportDir, "REPORT.md");
+    const reportJsonPath = join(reportDir, "report.json");
+    // 构建原始报告对象
+    const rawReport = {
+        goal_id: goalStatus.goal_id,
+        generated_at: generatedAt,
+        path: reportDir,
+        completion_rate: noSubgoals ? 0 : parseCompletionRate(summary.completion_rate),
+        files: { report_md: reportMdPath, report_json: reportJsonPath },
+        summary,
+        subgoals: subgoalEntries,
+        risks,
+        timeline: {
+            created_at: goalStatus.created_at,
+            updated_at: goalStatus.updated_at,
+            status: goalStatus.status,
+        },
+        bounded: true,
+    };
+    // 脱敏所有字符串内容
+    const safeReport = redactSensitiveValue(rawReport).value;
+    // 原子写 JSON（机器可读）
+    atomicWriteFileSync(reportJsonPath, JSON.stringify(safeReport, null, 2) + "\n");
+    // 原子写 Markdown（人类可读，从脱敏后的对象生成）
+    const markdown = buildReportMarkdown(safeReport, { noSubgoals, incomplete });
+    atomicWriteFileSync(reportMdPath, markdown);
+    return safeReport;
+}

package/dist/goal/goalStatus.d.ts

@@ -19,6 +19,12 @@ export interface Subgoal {
     task_ids: string[];
     accepted_at?: string;
     rejected_reason?: string;
+    /** Spec Kit task id 回溯（用于幂等去重） */
+    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;
@@ -28,6 +34,8 @@ export interface GoalStatus {
     created_at: string;
     updated_at: string;
     subgoals: Subgoal[];
+    /** Spec Kit 验收标准列表 */
+    acceptance_criteria?: string[];
 }
 /**
  * 创建初始 GoalStatus，用于新 goal。

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>;