patchwarden 0.6.4 → 1.5.0

package/dist/goal/goalStatus.js

@@ -0,0 +1,137 @@
+/**
+ * v0.8.0: Goal Session 子目标状态机 — 不可变更新 + 状态机校验。
+ *
+ * 类型定义：SubgoalStatus / Subgoal / GoalStatus
+ * 状态机合法转换：
+ *   ready → running
+ *   running → done_by_agent
+ *   done_by_agent → accepted | rejected | needs_fix
+ *   needs_fix → running
+ *
+ * 所有更新函数返回新的 GoalStatus 对象，不修改原对象。
+ */
+import { PatchWardenError } from "../errors.js";
+// ── 合法状态转换表 ────────────────────────────────────────────────
+const LEGAL_TRANSITIONS = {
+    ready: ["running"],
+    running: ["done_by_agent"],
+    done_by_agent: ["accepted", "rejected", "needs_fix"],
+    accepted: [],
+    rejected: [],
+    needs_fix: ["running"],
+};
+// ── 函数实现 ──────────────────────────────────────────────────────
+/**
+ * 创建初始 GoalStatus，用于新 goal。
+ * status 为 "active"，subgoals 为空数组，时间戳为当前 ISO 时间。
+ */
+export function createInitialGoalStatus(goalId, title, repoPath) {
+    const now = new Date().toISOString();
+    return {
+        goal_id: goalId,
+        title,
+        status: "active",
+        repo_path: repoPath,
+        created_at: now,
+        updated_at: now,
+        subgoals: [],
+    };
+}
+/**
+ * 向 goalStatus 添加一个新 subgoal。
+ * subgoal_id 格式：`subgoal-{NNN}`，NNN 三位补零，从 001 开始递增。
+ * 校验 dependsOn 中每个 id 是否存在于现有 subgoals。
+ * 不可变更新：返回新的 GoalStatus 对象。
+ */
+export function addSubgoal(goalStatus, title, dependsOn = []) {
+    const existingIds = new Set(goalStatus.subgoals.map((s) => s.id));
+    for (const depId of dependsOn) {
+        if (!existingIds.has(depId)) {
+            throw new PatchWardenError("invalid_dependency", `Subgoal dependency "${depId}" does not exist`, "Ensure depends_on references only existing subgoal ids.", true, { subgoal_id: depId, existing_ids: [...existingIds] });
+        }
+    }
+    const nextNumber = goalStatus.subgoals.length + 1;
+    const subgoalId = `subgoal-${String(nextNumber).padStart(3, "0")}`;
+    const newSubgoal = {
+        id: subgoalId,
+        title,
+        status: "ready",
+        depends_on: [...dependsOn],
+        task_ids: [],
+    };
+    const now = new Date().toISOString();
+    const updated = {
+        ...goalStatus,
+        subgoals: [...goalStatus.subgoals, newSubgoal],
+        updated_at: now,
+    };
+    return { goalStatus: updated, subgoalId };
+}
+/**
+ * 更新指定 subgoal 的状态，校验状态机合法转换。
+ * - accepted：设置 accepted_at
+ * - rejected：需要 options.rejected_reason
+ * 不可变更新：返回新的 GoalStatus 对象。
+ */
+export function updateSubgoalStatus(goalStatus, subgoalId, newStatus, options) {
+    const index = goalStatus.subgoals.findIndex((s) => s.id === subgoalId);
+    if (index === -1) {
+        throw new PatchWardenError("subgoal_not_found", `Subgoal "${subgoalId}" not found in goal "${goalStatus.goal_id}"`, "Ensure the subgoal id exists before updating its status.", true, { subgoal_id: subgoalId, goal_id: goalStatus.goal_id });
+    }
+    const current = goalStatus.subgoals[index];
+    const legal = LEGAL_TRANSITIONS[current.status];
+    if (!legal.includes(newStatus)) {
+        throw new PatchWardenError("invalid_status_transition", `Invalid status transition for subgoal "${subgoalId}": "${current.status}" -> "${newStatus}"`, `Valid transitions from "${current.status}": ${legal.length > 0 ? legal.join(", ") : "(none, terminal state)"}.`, true, {
+            subgoal_id: subgoalId,
+            from_status: current.status,
+            to_status: newStatus,
+            legal_transitions: legal,
+        });
+    }
+    const updatedSubgoal = {
+        ...current,
+        status: newStatus,
+    };
+    if (newStatus === "accepted") {
+        updatedSubgoal.accepted_at = new Date().toISOString();
+    }
+    if (newStatus === "rejected") {
+        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;
+    }
+    const newSubgoals = [...goalStatus.subgoals];
+    newSubgoals[index] = updatedSubgoal;
+    return {
+        ...goalStatus,
+        subgoals: newSubgoals,
+        updated_at: new Date().toISOString(),
+    };
+}
+/**
+ * 将 taskId 关联到指定 subgoal（去重）。
+ * 不可变更新：返回新的 GoalStatus 对象。
+ */
+export function linkTaskToSubgoal(goalStatus, subgoalId, taskId) {
+    const index = goalStatus.subgoals.findIndex((s) => s.id === subgoalId);
+    if (index === -1) {
+        throw new PatchWardenError("subgoal_not_found", `Subgoal "${subgoalId}" not found in goal "${goalStatus.goal_id}"`, "Ensure the subgoal id exists before linking a task.", true, { subgoal_id: subgoalId, goal_id: goalStatus.goal_id });
+    }
+    const current = goalStatus.subgoals[index];
+    if (current.task_ids.includes(taskId)) {
+        // 已存在，不重复添加，但仍返回等价的新对象以保持不可变契约
+        return { ...goalStatus, updated_at: new Date().toISOString() };
+    }
+    const updatedSubgoal = {
+        ...current,
+        task_ids: [...current.task_ids, taskId],
+    };
+    const newSubgoals = [...goalStatus.subgoals];
+    newSubgoals[index] = updatedSubgoal;
+    return {
+        ...goalStatus,
+        subgoals: newSubgoals,
+        updated_at: new Date().toISOString(),
+    };
+}

package/dist/goal/goalStore.d.ts

@@ -0,0 +1,79 @@
+/**
+ * v0.8.0: Goal Session 目录 CRUD — 在 workspaceRoot 下管理 .patchwarden/goals/ 目录。
+ *
+ * 目录结构：
+ *   {workspaceRoot}/.patchwarden/goals/{goal_id}/
+ *     ├── GOAL.md              人类可读的 goal 描述
+ *     ├── GOALS.md             子目标列表（人类可读）
+ *     ├── goal_status.json     机器可读的状态文件（原子写）
+ *     ├── tasks/               任务产物
+ *     └── artifacts/           其他产物
+ *
+ * 所有文件系统函数都接受可选的 workspaceRoot 参数用于测试；
+ * 默认从 getConfig().workspaceRoot 读取。
+ */
+import { type GoalStatus, type Subgoal } from "./goalStatus.js";
+/**
+ * 生成 `goal_{YYYYMMDD}_{slug}` 格式的 goal id。
+ * 冲突时追加 `_2`、`_3`... 直到唯一。
+ * 日期用本地时区（new Date()）。
+ */
+export declare function generateGoalId(title: string, existingIds: string[]): string;
+/**
+ * 返回 `.patchwarden/goals/` 目录路径（相对于 workspaceRoot）。
+ * 不自动创建目录。
+ */
+export declare function getGoalsDir(workspaceRoot?: string): string;
+/**
+ * 返回 `{getGoalsDir()}/{goalId}` 路径。
+ */
+export declare function getGoalDir(goalId: string, workspaceRoot?: string): string;
+/**
+ * 创建一个新的 Goal Session。
+ * - 用 guardWorkspacePath 校验 repoPath 在 workspaceRoot 内
+ * - 扫描现有 goal 目录获取 existingIds，调用 generateGoalId
+ * - 创建目录结构：goal_dir/、tasks/、artifacts/
+ * - 写入 GOAL.md、GOALS.md、goal_status.json
+ * 返回 { goal_id, goal_dir }。
+ */
+export declare function createGoal(repoPath: string, title: string, description: string, workspaceRoot?: string): {
+    goal_id: string;
+    goal_dir: string;
+};
+/**
+ * 列出所有 goal 的摘要信息，按 updated_at 降序排列。
+ * 无法解析的目录会被跳过。
+ */
+export declare function listGoals(workspaceRoot?: string): Array<{
+    goal_id: string;
+    title: string;
+    status: string;
+    subgoal_total: number;
+    subgoal_accepted: number;
+    subgoal_running: number;
+    updated_at: string;
+}>;
+/**
+ * 读取 goal 的完整详情：goal_status.json + GOAL.md 内容。
+ * 如果 goal 目录不存在或 goal_status.json 不存在，抛出 PatchWardenError("goal_not_found")。
+ */
+export declare function readGoal(goalId: string, workspaceRoot?: string): {
+    goal_id: string;
+    title: string;
+    status: string;
+    repo_path: string;
+    created_at: string;
+    updated_at: string;
+    goal_description: string;
+    subgoals: Subgoal[];
+};
+/**
+ * 原子写入 goal_status.json：先写到 .tmp 文件，再 renameSync。
+ * JSON 序列化用 JSON.stringify(status, null, 2) + 末尾换行。
+ */
+export declare function writeGoalStatus(goalId: string, status: GoalStatus, workspaceRoot?: string): void;
+/**
+ * 读取 goal_status.json 并 JSON.parse。
+ * 如果文件不存在，抛出 PatchWardenError("goal_not_found")。
+ */
+export declare function readGoalStatus(goalId: string, workspaceRoot?: string): GoalStatus;

package/dist/goal/goalStore.js

@@ -0,0 +1,211 @@
+/**
+ * v0.8.0: Goal Session 目录 CRUD — 在 workspaceRoot 下管理 .patchwarden/goals/ 目录。
+ *
+ * 目录结构：
+ *   {workspaceRoot}/.patchwarden/goals/{goal_id}/
+ *     ├── GOAL.md              人类可读的 goal 描述
+ *     ├── GOALS.md             子目标列表（人类可读）
+ *     ├── goal_status.json     机器可读的状态文件（原子写）
+ *     ├── tasks/               任务产物
+ *     └── artifacts/           其他产物
+ *
+ * 所有文件系统函数都接受可选的 workspaceRoot 参数用于测试；
+ * 默认从 getConfig().workspaceRoot 读取。
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync, statSync, } from "node:fs";
+import { join } from "node:path";
+import { getConfig } from "../config.js";
+import { guardWorkspacePath } from "../security/pathGuard.js";
+import { PatchWardenError } from "../errors.js";
+import { createInitialGoalStatus, } from "./goalStatus.js";
+// ── 辅助：解析 workspaceRoot ──────────────────────────────────────
+function resolveWorkspaceRoot(workspaceRoot) {
+    return workspaceRoot ?? getConfig().workspaceRoot;
+}
+// ── Goal ID 生成 ──────────────────────────────────────────────────
+/**
+ * 从 title 生成 slug：小写、非字母数字字符替换为 `_`、合并连续 `_`、去除首尾 `_`、截断到 30 字符。
+ * 如果 slug 为空（title 全是符号），用 `untitled` 代替。
+ */
+function titleToSlug(title) {
+    const slug = title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "")
+        .slice(0, 30);
+    return slug === "" ? "untitled" : slug;
+}
+/**
+ * 生成 `goal_{YYYYMMDD}_{slug}` 格式的 goal id。
+ * 冲突时追加 `_2`、`_3`... 直到唯一。
+ * 日期用本地时区（new Date()）。
+ */
+export function generateGoalId(title, existingIds) {
+    const now = new Date();
+    const y = now.getFullYear();
+    const m = String(now.getMonth() + 1).padStart(2, "0");
+    const d = String(now.getDate()).padStart(2, "0");
+    const datePart = `${y}${m}${d}`;
+    const slug = titleToSlug(title);
+    const existing = new Set(existingIds);
+    const base = `goal_${datePart}_${slug}`;
+    if (!existing.has(base)) {
+        return base;
+    }
+    let counter = 2;
+    while (existing.has(`${base}_${counter}`)) {
+        counter++;
+    }
+    return `${base}_${counter}`;
+}
+// ── 目录路径解析 ──────────────────────────────────────────────────
+/**
+ * 返回 `.patchwarden/goals/` 目录路径（相对于 workspaceRoot）。
+ * 不自动创建目录。
+ */
+export function getGoalsDir(workspaceRoot) {
+    return join(resolveWorkspaceRoot(workspaceRoot), ".patchwarden", "goals");
+}
+/**
+ * 返回 `{getGoalsDir()}/{goalId}` 路径。
+ */
+export function getGoalDir(goalId, workspaceRoot) {
+    return join(getGoalsDir(workspaceRoot), goalId);
+}
+// ── CRUD ──────────────────────────────────────────────────────────
+/**
+ * 创建一个新的 Goal Session。
+ * - 用 guardWorkspacePath 校验 repoPath 在 workspaceRoot 内
+ * - 扫描现有 goal 目录获取 existingIds，调用 generateGoalId
+ * - 创建目录结构：goal_dir/、tasks/、artifacts/
+ * - 写入 GOAL.md、GOALS.md、goal_status.json
+ * 返回 { goal_id, goal_dir }。
+ */
+export function createGoal(repoPath, title, description, workspaceRoot) {
+    const wsRoot = resolveWorkspaceRoot(workspaceRoot);
+    const guardedRepo = guardWorkspacePath(repoPath, wsRoot);
+    const goalsDir = getGoalsDir(workspaceRoot);
+    const existingIds = [];
+    if (existsSync(goalsDir)) {
+        for (const entry of readdirSync(goalsDir)) {
+            const entryPath = join(goalsDir, entry);
+            try {
+                if (statSync(entryPath).isDirectory()) {
+                    existingIds.push(entry);
+                }
+            }
+            catch {
+                // 跳过无法 stat 的条目
+            }
+        }
+    }
+    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 };
+}
+/**
+ * 列出所有 goal 的摘要信息，按 updated_at 降序排列。
+ * 无法解析的目录会被跳过。
+ */
+export function listGoals(workspaceRoot) {
+    const goalsDir = getGoalsDir(workspaceRoot);
+    if (!existsSync(goalsDir)) {
+        return [];
+    }
+    const results = [];
+    for (const entry of readdirSync(goalsDir)) {
+        const entryPath = join(goalsDir, entry);
+        try {
+            if (!statSync(entryPath).isDirectory()) {
+                continue;
+            }
+            const status = readGoalStatus(entry, workspaceRoot);
+            results.push({
+                goal_id: status.goal_id,
+                title: status.title,
+                status: status.status,
+                subgoal_total: status.subgoals.length,
+                subgoal_accepted: status.subgoals.filter((s) => s.status === "accepted").length,
+                subgoal_running: status.subgoals.filter((s) => s.status === "running").length,
+                updated_at: status.updated_at,
+            });
+        }
+        catch {
+            // 跳过无法解析的目录
+        }
+    }
+    results.sort((a, b) => (a.updated_at < b.updated_at ? 1 : a.updated_at > b.updated_at ? -1 : 0));
+    return results;
+}
+/**
+ * 读取 goal 的完整详情：goal_status.json + GOAL.md 内容。
+ * 如果 goal 目录不存在或 goal_status.json 不存在，抛出 PatchWardenError("goal_not_found")。
+ */
+export function readGoal(goalId, workspaceRoot) {
+    const goalDir = getGoalDir(goalId, workspaceRoot);
+    if (!existsSync(goalDir)) {
+        throw new PatchWardenError("goal_not_found", `Goal directory not found: "${goalDir}"`, "Ensure the goal id exists before reading.", true, { goal_id: goalId, goal_dir: goalDir });
+    }
+    const status = readGoalStatus(goalId, workspaceRoot);
+    let goalDescription = "";
+    const goalMdPath = join(goalDir, "GOAL.md");
+    if (existsSync(goalMdPath)) {
+        goalDescription = readFileSync(goalMdPath, "utf-8");
+    }
+    return {
+        goal_id: status.goal_id,
+        title: status.title,
+        status: status.status,
+        repo_path: status.repo_path,
+        created_at: status.created_at,
+        updated_at: status.updated_at,
+        goal_description: goalDescription,
+        subgoals: status.subgoals,
+    };
+}
+/**
+ * 原子写入 goal_status.json：先写到 .tmp 文件，再 renameSync。
+ * JSON 序列化用 JSON.stringify(status, null, 2) + 末尾换行。
+ */
+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);
+}
+/**
+ * 读取 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");
+    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);
+}

package/dist/goal/handoffExport.d.ts

@@ -0,0 +1,34 @@
+/**
+ * v0.8.0: Goal Session 交接文档生成 — 将当前 goal 状态渲染为 Markdown 交接报告。
+ *
+ * generateHandoff 生成 Markdown 字符串；exportHandoff 将其落盘到
+ * {workspaceRoot}/.patchwarden/goals/{goalId}/handoff.md。
+ * exportHandoff 接受调用方传入的 goalStatus，不自行读取 goal_status.json，
+ * 以避免与 goalStore 形成循环依赖。
+ */
+import type { GoalStatus } from "./goalStatus.js";
+/**
+ * 生成 Goal Session 交接文档（Markdown 字符串）。
+ *
+ * 包含章节：当前 Goal、版本目标、已完成/未完成/已拒绝子目标、最近 diff 摘要、
+ * 最近测试结果、当前阻塞点、下一步建议、风险提醒、接手说明。
+ *
+ * @param goalId          Goal 标识（用于接手说明中的引用）
+ * @param goalStatus      当前 GoalStatus 快照
+ * @param recentDiff      最近一次 git diff 摘要（可选）
+ * @param recentTestResult 最近一次测试结果（可选）
+ * @returns Markdown 格式的交接文档
+ */
+export declare function generateHandoff(goalId: string, goalStatus: GoalStatus, recentDiff?: string, recentTestResult?: string): string;
+/**
+ * 生成交接文档并写入 {workspaceRoot}/.patchwarden/goals/{goalId}/handoff.md。
+ *
+ * @param goalId        Goal 标识
+ * @param goalStatus    当前 GoalStatus 快照（由调用方读取后传入）
+ * @param workspaceRoot 工作区根目录（可选，默认从 getConfig().workspaceRoot 获取）
+ * @returns handoff_path（绝对路径）和 content_preview（前 500 字符，超出则追加 "..."）
+ */
+export declare function exportHandoff(goalId: string, goalStatus: GoalStatus, workspaceRoot?: string): {
+    handoff_path: string;
+    content_preview: string;
+};

package/dist/goal/handoffExport.js

@@ -0,0 +1,183 @@
+/**
+ * v0.8.0: Goal Session 交接文档生成 — 将当前 goal 状态渲染为 Markdown 交接报告。
+ *
+ * generateHandoff 生成 Markdown 字符串；exportHandoff 将其落盘到
+ * {workspaceRoot}/.patchwarden/goals/{goalId}/handoff.md。
+ * exportHandoff 接受调用方传入的 goalStatus，不自行读取 goal_status.json，
+ * 以避免与 goalStore 形成循环依赖。
+ */
+import { suggestNextSubgoal } from "./goalGraph.js";
+import { getConfig } from "../config.js";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+// ── Markdown 生成 ────────────────────────────────────────────────
+/**
+ * 生成 Goal Session 交接文档（Markdown 字符串）。
+ *
+ * 包含章节：当前 Goal、版本目标、已完成/未完成/已拒绝子目标、最近 diff 摘要、
+ * 最近测试结果、当前阻塞点、下一步建议、风险提醒、接手说明。
+ *
+ * @param goalId          Goal 标识（用于接手说明中的引用）
+ * @param goalStatus      当前 GoalStatus 快照
+ * @param recentDiff      最近一次 git diff 摘要（可选）
+ * @param recentTestResult 最近一次测试结果（可选）
+ * @returns Markdown 格式的交接文档
+ */
+export function generateHandoff(goalId, goalStatus, recentDiff, recentTestResult) {
+    const lines = [];
+    const now = new Date().toISOString();
+    lines.push("# Goal Session Handoff");
+    lines.push("");
+    lines.push("Generated: " + now);
+    lines.push("");
+    // ── 当前 Goal ───────────────────────────────────────────
+    lines.push("## 当前 Goal");
+    lines.push("");
+    lines.push("- **goal_id**: " + goalStatus.goal_id);
+    lines.push("- **title**: " + goalStatus.title);
+    lines.push("- **status**: " + goalStatus.status);
+    lines.push("- **repo_path**: " + goalStatus.repo_path);
+    lines.push("");
+    // ── 版本目标 ────────────────────────────────────────────
+    lines.push("## 版本目标");
+    lines.push("");
+    lines.push(goalStatus.title);
+    lines.push("");
+    // ── 已完成子目标 ────────────────────────────────────────
+    lines.push("## 已完成子目标");
+    lines.push("");
+    const accepted = goalStatus.subgoals.filter((s) => s.status === "accepted");
+    if (accepted.length === 0) {
+        lines.push("无");
+    }
+    else {
+        for (const s of accepted) {
+            lines.push("- **" + s.id + "**: " + s.title + " (accepted_at: " + (s.accepted_at ?? "N/A") + ")");
+        }
+    }
+    lines.push("");
+    // ── 未完成子目标 ────────────────────────────────────────
+    lines.push("## 未完成子目标");
+    lines.push("");
+    const incomplete = goalStatus.subgoals.filter((s) => s.status !== "accepted" && s.status !== "rejected");
+    if (incomplete.length === 0) {
+        lines.push("无");
+    }
+    else {
+        for (const s of incomplete) {
+            const deps = s.depends_on.length > 0 ? s.depends_on.join(", ") : "无";
+            lines.push("- **" + s.id + "**: " + s.title + " (status: " + s.status + ", depends_on: " + deps + ")");
+        }
+    }
+    lines.push("");
+    // ── 已拒绝子目标 ────────────────────────────────────────
+    lines.push("## 已拒绝子目标");
+    lines.push("");
+    const rejected = goalStatus.subgoals.filter((s) => s.status === "rejected");
+    if (rejected.length === 0) {
+        lines.push("无");
+    }
+    else {
+        for (const s of rejected) {
+            lines.push("- **" + s.id + "**: " + s.title + " (rejected_reason: " + (s.rejected_reason ?? "N/A") + ")");
+        }
+    }
+    lines.push("");
+    // ── 最近一次 diff 摘要 ──────────────────────────────────
+    lines.push("## 最近一次 diff 摘要");
+    lines.push("");
+    if (recentDiff) {
+        lines.push(recentDiff);
+    }
+    else {
+        lines.push("暂无");
+    }
+    lines.push("");
+    // ── 最近一次测试结果 ────────────────────────────────────
+    lines.push("## 最近一次测试结果");
+    lines.push("");
+    if (recentTestResult) {
+        lines.push(recentTestResult);
+    }
+    else {
+        lines.push("暂无");
+    }
+    lines.push("");
+    // ── 当前阻塞点 ─────────────────────────────────────────
+    lines.push("## 当前阻塞点");
+    lines.push("");
+    const needsFix = goalStatus.subgoals.filter((s) => s.status === "needs_fix");
+    if (needsFix.length === 0) {
+        lines.push("无");
+    }
+    else {
+        for (const s of needsFix) {
+            lines.push("- **" + s.id + "**: " + s.title);
+        }
+    }
+    lines.push("");
+    // ── 下一步建议 ─────────────────────────────────────────
+    lines.push("## 下一步建议");
+    lines.push("");
+    const suggestion = suggestNextSubgoal(goalStatus);
+    if (suggestion.subgoal_id) {
+        lines.push("建议执行子目标 **" + suggestion.subgoal_id + "**：" + (suggestion.title ?? ""));
+    }
+    else if (suggestion.reason === "dependencies_not_met") {
+        lines.push("当前存在被阻塞的子目标，建议先处理以下依赖：");
+        const blockedList = suggestion.blocked_by ?? [];
+        for (const id of blockedList) {
+            lines.push("- " + id);
+        }
+    }
+    else {
+        lines.push("当前无可执行的 ready 子目标，建议检查所有子目标状态或等待任务完成。");
+    }
+    lines.push("");
+    // ── 风险提醒 ───────────────────────────────────────────
+    lines.push("## 风险提醒");
+    lines.push("");
+    const risks = goalStatus.subgoals.filter((s) => s.status === "needs_fix" || s.status === "running");
+    if (risks.length === 0) {
+        lines.push("无");
+    }
+    else {
+        for (const s of risks) {
+            if (s.status === "needs_fix") {
+                lines.push("- **" + s.id + "**: " + s.title + " (needs_fix — 需要修复)");
+            }
+            else {
+                lines.push("- **" + s.id + "**: " + s.title + " (running — 长期运行中)");
+            }
+        }
+    }
+    lines.push("");
+    // ── 接手说明 ───────────────────────────────────────────
+    lines.push("## 接手说明");
+    lines.push("");
+    lines.push("新会话接手时，请先调用 read_goal 查看 " + goalId + " 的完整状态，然后调用 suggest_next_subgoal 获取下一个可执行子目标。");
+    lines.push("");
+    return lines.join("\n");
+}
+// ── 落盘导出 ─────────────────────────────────────────────────────
+/**
+ * 生成交接文档并写入 {workspaceRoot}/.patchwarden/goals/{goalId}/handoff.md。
+ *
+ * @param goalId        Goal 标识
+ * @param goalStatus    当前 GoalStatus 快照（由调用方读取后传入）
+ * @param workspaceRoot 工作区根目录（可选，默认从 getConfig().workspaceRoot 获取）
+ * @returns handoff_path（绝对路径）和 content_preview（前 500 字符，超出则追加 "..."）
+ */
+export function exportHandoff(goalId, goalStatus, workspaceRoot) {
+    const content = generateHandoff(goalId, goalStatus);
+    const root = workspaceRoot ?? getConfig().workspaceRoot;
+    const goalDir = resolve(root, ".patchwarden", "goals", goalId);
+    mkdirSync(goalDir, { recursive: true });
+    const handoffPath = join(goalDir, "handoff.md");
+    writeFileSync(handoffPath, content, "utf-8");
+    const preview = content.length > 500 ? content.slice(0, 500) + "..." : content;
+    return {
+        handoff_path: handoffPath,
+        content_preview: preview,
+    };
+}