patchwarden 0.6.1 → 1.1.0

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,
+    };
+}

package/dist/goal/subgoalSync.d.ts

@@ -0,0 +1,40 @@
+/**
+ * v0.8.0: Subgoal 状态同步 — 当任务状态变为 done_by_agent 时回写关联 subgoal 状态。
+ *
+ * 设计原则：
+ *   - 向后兼容：无 goal_id/subgoal_id 关联的任务直接返回，不影响现有流程。
+ *   - 错误隔离：subgoal 同步失败只记录到 stderr，不阻断任务完成主流程。
+ *   - 仅同步 running → done_by_agent 转换；其他状态由 audit_task / 显式 API 处理。
+ */
+/**
+ * v0.8.0: 当任务状态变为 done_by_agent 时，同步更新关联的 subgoal 状态。
+ *
+ * 行为：
+ *   - 如果 taskMeta.subgoal_id 或 goal_id 为 null/undefined，直接返回（向后兼容）。
+ *   - 读取 goal_status.json，找到对应 subgoal。
+ *   - 仅当 subgoal 当前状态为 "running" 时，更新为 "done_by_agent"。
+ *   - 其他状态（ready/accepted/rejected/needs_fix/done_by_agent）保持不变。
+ *   - 所有操作用 try/catch 包裹，失败时只记录到 stderr 不阻断主流程。
+ *
+ * @param taskId 任务 id（仅用于日志）
+ * @param taskMeta 任务的 goal 关联元信息（goal_id / subgoal_id）
+ * @param workspaceRoot 可选的工作区根目录（测试用），默认从 getConfig() 读取
+ */
+export declare function syncSubgoalOnTaskDone(taskId: string, taskMeta: {
+    goal_id?: string | null;
+    subgoal_id?: string | null;
+}, workspaceRoot?: string): void;
+/**
+ * v0.8.0: 从 task 的 status.json 读取 goal_id/subgoal_id 关联信息。
+ *
+ * 行为：
+ *   - 读取 {taskDir}/status.json，解析其中的 goal_id / subgoal_id 字段。
+ *   - 任何错误（文件不存在、JSON 解析失败等）都返回 { goal_id: null, subgoal_id: null }，
+ *     不抛错，保证调用方流程不受影响。
+ *
+ * @param taskDir 任务目录路径（包含 status.json）
+ */
+export declare function readTaskGoalMeta(taskDir: string): {
+    goal_id: string | null;
+    subgoal_id: string | null;
+};

package/dist/goal/subgoalSync.js

@@ -0,0 +1,72 @@
+/**
+ * v0.8.0: Subgoal 状态同步 — 当任务状态变为 done_by_agent 时回写关联 subgoal 状态。
+ *
+ * 设计原则：
+ *   - 向后兼容：无 goal_id/subgoal_id 关联的任务直接返回，不影响现有流程。
+ *   - 错误隔离：subgoal 同步失败只记录到 stderr，不阻断任务完成主流程。
+ *   - 仅同步 running → done_by_agent 转换；其他状态由 audit_task / 显式 API 处理。
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { readGoalStatus, writeGoalStatus } from "./goalStore.js";
+import { updateSubgoalStatus } from "./goalStatus.js";
+// ── 同步函数 ──────────────────────────────────────────────────────
+/**
+ * v0.8.0: 当任务状态变为 done_by_agent 时，同步更新关联的 subgoal 状态。
+ *
+ * 行为：
+ *   - 如果 taskMeta.subgoal_id 或 goal_id 为 null/undefined，直接返回（向后兼容）。
+ *   - 读取 goal_status.json，找到对应 subgoal。
+ *   - 仅当 subgoal 当前状态为 "running" 时，更新为 "done_by_agent"。
+ *   - 其他状态（ready/accepted/rejected/needs_fix/done_by_agent）保持不变。
+ *   - 所有操作用 try/catch 包裹，失败时只记录到 stderr 不阻断主流程。
+ *
+ * @param taskId 任务 id（仅用于日志）
+ * @param taskMeta 任务的 goal 关联元信息（goal_id / subgoal_id）
+ * @param workspaceRoot 可选的工作区根目录（测试用），默认从 getConfig() 读取
+ */
+export function syncSubgoalOnTaskDone(taskId, taskMeta, workspaceRoot) {
+    const goalId = taskMeta.goal_id;
+    const subgoalId = taskMeta.subgoal_id;
+    if (!goalId || !subgoalId)
+        return;
+    try {
+        const goalStatus = readGoalStatus(goalId, workspaceRoot);
+        const subgoal = goalStatus.subgoals.find((s) => s.id === subgoalId);
+        if (!subgoal)
+            return;
+        if (subgoal.status !== "running")
+            return;
+        const updated = updateSubgoalStatus(goalStatus, subgoalId, "done_by_agent");
+        writeGoalStatus(goalId, updated, workspaceRoot);
+    }
+    catch (err) {
+        // subgoal 同步失败不应影响任务完成流程，只记录到 stderr
+        console.error(`[goal] syncSubgoalOnTaskDone failed for task ${taskId}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+// ── Task 元信息读取 ───────────────────────────────────────────────
+/**
+ * v0.8.0: 从 task 的 status.json 读取 goal_id/subgoal_id 关联信息。
+ *
+ * 行为：
+ *   - 读取 {taskDir}/status.json，解析其中的 goal_id / subgoal_id 字段。
+ *   - 任何错误（文件不存在、JSON 解析失败等）都返回 { goal_id: null, subgoal_id: null }，
+ *     不抛错，保证调用方流程不受影响。
+ *
+ * @param taskDir 任务目录路径（包含 status.json）
+ */
+export function readTaskGoalMeta(taskDir) {
+    try {
+        const statusFile = join(taskDir, "status.json");
+        const raw = readFileSync(statusFile, "utf-8");
+        const data = JSON.parse(raw);
+        return {
+            goal_id: typeof data.goal_id === "string" ? data.goal_id : null,
+            subgoal_id: typeof data.subgoal_id === "string" ? data.subgoal_id : null,
+        };
+    }
+    catch {
+        return { goal_id: null, subgoal_id: null };
+    }
+}

package/dist/goal/worktreeManager.d.ts

@@ -0,0 +1,96 @@
+/**
+ * v1.0.0 Part B: Worktree 隔离管理器 — 在 workspaceRoot 下管理 git worktree，
+ * 为每个 subgoal task 提供独立的代码副本，避免并发任务互相污染工作区。
+ *
+ * 目录结构：
+ *   {workspaceRoot}/_workspacetrees/{worktree_id}/
+ *     └── worktree_status.json   机器可读的状态文件（原子写）
+ *   {workspaceRoot}/.patchwarden/worktree-archive/{worktree_id}.json
+ *     归档的已 discard 状态（worktree 目录被删除后保留审计记录）
+ *
+ * 安全约束：
+ *   - 所有路径经 guardWorkspacePath + guardSensitivePath 校验
+ *   - git 命令只用 child_process.execFileSync（不使用 shell），白名单仅
+ *     git worktree add/remove/prune + git merge + git branch
+ *   - createWorktree 失败时清理半成品 worktree 目录与临时 branch
+ *   - 不暴露通用 shell，不 blanket-kill watcher（worktree 与 watcher 无关）
+ *
+ * 所有文件系统函数都接受可选的 workspaceRoot 参数用于测试；
+ * 默认从 getConfig().workspaceRoot 读取。
+ */
+export interface WorktreeStatus {
+    worktree_id: string;
+    goal_id: string;
+    subgoal_id: string;
+    path: string;
+    created_at: string;
+    status: "active" | "merged" | "discarded";
+    branch: string;
+    merged_at?: string;
+    discarded_at?: string;
+}
+/** worktree 根目录名，放在 workspaceRoot 下。 */
+export declare const WorktreeDir = "_workspacetrees";
+/**
+ * 返回 `<workspaceRoot>/_workspacetrees` 目录路径。不自动创建目录。
+ */
+export declare function getWorktreesDir(workspaceRoot?: string): string;
+/**
+ * 返回 `<getWorktreesDir()>/<worktreeId>` 路径。
+ */
+export declare function getWorktreeDir(worktreeId: string, workspaceRoot?: string): string;
+/**
+ * 为指定 goal/subgoal 创建一个隔离的 git worktree。
+ *
+ * 流程：
+ *   1. 生成 worktreeId（内部随机），拼出 worktreePath 与 branch
+ *   2. guardWorkspacePath + guardSensitivePath 校验路径
+ *   3. `git worktree add -b <branch> <worktreePath>` 创建 worktree
+ *   4. 原子写入 worktree_status.json（status="active"）
+ *
+ * 失败时清理：若 git worktree add 或写 status 失败，移除已创建的 worktree
+ * 目录与临时 branch，抛出 PatchWardenError("worktree_create_failed")。
+ *
+ * @returns { worktreeId, worktreePath, branch }
+ */
+export declare function createWorktree(goalId: string, subgoalId: string, workspaceRoot: string): {
+    worktreeId: string;
+    worktreePath: string;
+    branch: string;
+};
+/**
+ * 读取 worktree_status.json。不存在返回 null。
+ * 路径逃逸或敏感路径会抛 PatchWardenError（不静默吞掉安全违规）。
+ */
+export declare function readWorktreeStatus(worktreeId: string, workspaceRoot?: string): WorktreeStatus | null;
+/**
+ * 将 worktree 的 branch 合并回主工作区（workspaceRoot）。
+ *
+ * 流程：
+ *   1. 读取 worktree_status.json，校验 status === "active"
+ *   2. `git merge <branch>`（在 workspaceRoot 执行）
+ *   3. 原子更新 worktree_status.json：status="merged"，merged_at=ISO timestamp
+ *
+ * 合并失败时抛 PatchWardenError("worktree_merge_failed")，不删除 worktree
+ * （保留供人工排查冲突）。
+ */
+export declare function mergeWorktree(worktreeId: string, workspaceRoot: string): {
+    status: "merged";
+};
+/**
+ * 丢弃 worktree：移除 worktree 目录与临时 branch，归档最终状态。
+ *
+ * 流程：
+ *   1. 读取 worktree_status.json（在 remove 之前读取，因为 status 文件位于
+ *      worktree 目录内），校验 status === "active"
+ *   2. `git worktree remove --force <worktreePath>`
+ *   3. `git branch -D <branch>` 删除临时 branch
+ *   4. 把更新后的 status（discarded）写到归档目录
+ *      `<workspaceRoot>/.patchwarden/worktree-archive/<worktreeId>.json`
+ *      （.patchwarden 始终为安全路径，用 guardWorkspacePath 校验）
+ *
+ * 移除失败抛 PatchWardenError("worktree_discard_failed")。
+ */
+export declare function discardWorktree(worktreeId: string, workspaceRoot: string): {
+    status: "discarded";
+};