patchwarden 0.4.0

package/dist/tools/registry.js

@@ -0,0 +1,566 @@
+/**
+ * Shared tool registry for PatchWarden MCP server.
+ * Used by both stdio (index.ts) and HTTP (httpServer.ts) transports.
+ */
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { getConfig } from "../config.js";
+import { savePlan } from "../tools/savePlan.js";
+import { getPlan } from "../tools/getPlan.js";
+import { createTask } from "../tools/createTask.js";
+import { getTaskStatus } from "../tools/getTaskStatus.js";
+import { getResult, getResultJson, getDiff, getTestLog, getTaskLogTail } from "../tools/taskOutputs.js";
+import { listWorkspace } from "../tools/listWorkspace.js";
+import { readWorkspaceFile } from "../tools/readWorkspaceFile.js";
+import { listTasks } from "../tools/listTasks.js";
+import { cancelTask } from "../tools/cancelTask.js";
+import { killTask } from "../tools/killTask.js";
+import { retryTask } from "../tools/retryTask.js";
+import { getTaskStdoutTail } from "../tools/getTaskStdoutTail.js";
+import { getTaskProgress } from "../tools/getTaskProgress.js";
+import { listAgents } from "../tools/listAgents.js";
+import { healthCheck } from "../tools/healthCheck.js";
+import { getTaskSummary } from "../tools/getTaskSummary.js";
+import { waitForTask } from "../tools/waitForTask.js";
+import { errorPayload, PatchWardenError } from "../errors.js";
+import { auditTask } from "../tools/auditTask.js";
+import { runTask } from "../runner/runTask.js";
+import { TASK_TEMPLATE_NAMES } from "./taskTemplates.js";
+import { buildToolCatalogSnapshot, getLastToolCatalogSnapshot, resolveToolProfile, selectToolsForProfile, } from "./toolCatalog.js";
+export function getToolDefs() {
+    const config = getConfig();
+    const agentNames = Object.keys(config.agents).sort();
+    const agentDescription = agentNames.length > 0
+        ? `Configured local agent name. Available agents: ${agentNames.map((name) => JSON.stringify(name)).join(", ")}`
+        : "Configured local agent name. No agents are currently configured.";
+    const testCommands = [...config.allowedTestCommands].sort();
+    const tools = [
+        {
+            name: "save_plan",
+            description: "Save an execution plan — ChatGPT writes the plan, PatchWarden stores it for local agent execution.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    title: { type: "string", description: "Plan title" },
+                    content: { type: "string", description: "Plan content in Markdown" },
+                },
+                required: ["title", "content"],
+            },
+        },
+        {
+            name: "get_plan",
+            description: "Read a saved plan by its plan_id.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    plan_id: { type: "string", description: "Plan ID returned by save_plan" },
+                },
+                required: ["plan_id"],
+            },
+        },
+        {
+            name: "health_check",
+            description: "Check MCP catalog consistency, watcher freshness/supervisor state, workspace readiness, and configured agents. Use detail=self_diagnostic for expanded read-only evidence.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    detail: {
+                        type: "string",
+                        enum: ["standard", "self_diagnostic"],
+                        default: "standard",
+                        description: "Use self_diagnostic for catalog, watcher, agent, allowlist, workspace, and recent failure evidence.",
+                    },
+                },
+            },
+        },
+        {
+            name: "list_agents",
+            description: "List configured local agents and check whether each executable currently exists. This does not start an agent or contact its model provider.",
+            inputSchema: {
+                type: "object",
+                properties: {},
+            },
+        },
+        {
+            name: "create_task",
+            description: "Create a repo-scoped task from exactly one source. A stale watcher preserves the task but returns execution_blocked and directs the client to health_check; otherwise call wait_for_task until terminal.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    plan_id: { type: "string", description: "Plan ID from save_plan" },
+                    inline_plan: { type: "string", description: "Inline Markdown plan. It is safety-checked and persisted as an auditable saved plan before task creation." },
+                    plan_title: { type: "string", description: "Optional title used when inline_plan is supplied." },
+                    template: {
+                        type: "string",
+                        enum: [...TASK_TEMPLATE_NAMES],
+                        description: "Built-in guarded task template. Use with goal; rollback_scope_violation also requires source_task_id.",
+                    },
+                    goal: { type: "string", description: "Required task goal when template is supplied." },
+                    source_task_id: { type: "string", description: "Required source task for rollback_scope_violation review." },
+                    agent: {
+                        type: "string",
+                        description: agentDescription,
+                        ...(agentNames.length > 0 ? { enum: agentNames } : {}),
+                    },
+                    repo_path: {
+                        type: "string",
+                        description: "Required repository path inside workspaceRoot. No implicit workspace-root fallback is allowed.",
+                    },
+                    test_command: {
+                        type: "string",
+                        description: testCommands.length
+                            ? `Optional exact-match verification command. Allowed: ${testCommands.map((command) => JSON.stringify(command)).join(", ")}`
+                            : "Optional exact-match verification command. No commands are currently allowed.",
+                        ...(testCommands.length > 0 ? { enum: testCommands } : {}),
+                    },
+                    verify_commands: {
+                        type: "array",
+                        maxItems: 20,
+                        items: {
+                            type: "string",
+                            ...(testCommands.length > 0 ? { enum: testCommands } : {}),
+                        },
+                        description: "Recommended allow-listed commands PatchWarden runs independently after the agent exits.",
+                    },
+                    timeout_seconds: {
+                        type: "integer",
+                        minimum: 1,
+                        maximum: config.maxTaskTimeoutSeconds,
+                        default: config.defaultTaskTimeoutSeconds,
+                        description: `Total task timeout in seconds (default ${config.defaultTaskTimeoutSeconds}, max ${config.maxTaskTimeoutSeconds})`,
+                    },
+                },
+                required: ["agent", "repo_path"],
+            },
+        },
+        {
+            name: "get_task_status",
+            description: "Check task status, execution phase, watcher health, pending reason, current command, timeout, and change evidence.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    task_id: { type: "string", description: "Task ID from create_task" },
+                },
+                required: ["task_id"],
+            },
+        },
+        {
+            name: "get_result",
+            description: "Read result.md, or return structured availability and watcher evidence while the task is not terminal.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    task_id: { type: "string", description: "Task ID" },
+                },
+                required: ["task_id"],
+            },
+        },
+        {
+            name: "get_result_json",
+            description: "Read the structured result.json for deterministic task acceptance.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    task_id: { type: "string", description: "Task ID" },
+                },
+                required: ["task_id"],
+            },
+        },
+        {
+            name: "get_diff",
+            description: "Read task diff evidence, or return structured availability and watcher evidence while it is not ready.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    task_id: { type: "string", description: "Task ID" },
+                },
+                required: ["task_id"],
+            },
+        },
+        {
+            name: "get_test_log",
+            description: "Read test.log, or return structured availability and watcher evidence while it is not ready.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    task_id: { type: "string", description: "Task ID" },
+                },
+                required: ["task_id"],
+            },
+        },
+        {
+            name: "list_workspace",
+            description: "List files and directories within the workspace (sensitive files excluded).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: {
+                        type: "string",
+                        description: "Optional relative path within workspace (default: root)",
+                    },
+                },
+            },
+        },
+        {
+            name: "read_workspace_file",
+            description: "Read a file within the workspace. Sensitive files (secrets, keys, tokens) are blocked.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: {
+                        type: "string",
+                        description: "Relative path to a file inside the workspace",
+                    },
+                },
+                required: ["path"],
+            },
+        },
+        {
+            name: "list_tasks",
+            description: "List recent tasks with status/repo/active filters plus watcher state and computed pending reasons.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    status: {
+                        type: "string",
+                        description: "Filter by status: pending, running, done, failed, failed_verification, failed_scope_violation, failed_policy_violation, canceled",
+                    },
+                    limit: {
+                        type: "number",
+                        description: "Max tasks to return (default 20, max 100)",
+                    },
+                    repo_path: {
+                        type: "string",
+                        description: "Optional exact repo_path or resolved_repo_path filter.",
+                    },
+                    active_only: {
+                        type: "boolean",
+                        description: "When true, return only pending and running tasks.",
+                    },
+                },
+            },
+        },
+        {
+            name: "cancel_task",
+            description: "Request graceful cancellation. The runner that owns the child process performs termination; the MCP server never kills a PID read from task files.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    task_id: { type: "string", description: "Task ID to cancel" },
+                },
+                required: ["task_id"],
+            },
+        },
+        {
+            name: "kill_task",
+            description: "Request immediate termination of a pending or running task. The runner validates and kills only the child process it owns.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    task_id: { type: "string", description: "Task ID to terminate" },
+                },
+                required: ["task_id"],
+            },
+        },
+        {
+            name: "retry_task",
+            description: "Create a new task with the same plan, agent, repo_path, and test_command as an existing task. The original task is unchanged.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    task_id: { type: "string", description: "Task ID to retry" },
+                },
+                required: ["task_id"],
+            },
+        },
+        {
+            name: "get_task_stdout_tail",
+            description: "Read the last N lines of agent stdout/stderr. Reads from real-time stdout.log/stderr.log during execution, falls back to result.md after completion. Works on pending, running, and completed tasks. Default 80 lines.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    task_id: { type: "string", description: "Task ID" },
+                    lines: { type: "number", description: "Tail line count (default 80, max 200)" },
+                },
+                required: ["task_id"],
+            },
+        },
+        {
+            name: "get_task_log_tail",
+            description: "Read the last N lines of a task log file (stdout/stderr/test/verify) with automatic secret redaction. Default 80 lines, max 200. Always returns tail only — never the full file. Use this instead of read_workspace_file to avoid triggering platform content filters on log output.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    task_id: { type: "string", description: "Task ID" },
+                    file: {
+                        type: "string",
+                        enum: ["stdout", "stderr", "test", "verify"],
+                        description: "Log file to read: stdout (stdout.log), stderr (stderr.log), test (test.log), verify (verify.log)",
+                    },
+                    lines: { type: "number", description: "Tail line count (default 80, max 200)" },
+                    redact: { type: "boolean", description: "Apply secret redaction (default true)" },
+                },
+                required: ["task_id", "file"],
+            },
+        },
+        {
+            name: "get_task_progress",
+            description: "Read progress.md for task phases and the most recent heartbeat/current command.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    task_id: { type: "string", description: "Task ID" },
+                },
+                required: ["task_id"],
+            },
+        },
+        {
+            name: "wait_for_task",
+            description: "Long-poll a task for up to 30 seconds. If continuation_required=true, call wait_for_task again immediately and do not finish the assistant turn. Terminal responses include get_task_summary acceptance evidence.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    task_id: { type: "string", description: "Task ID from create_task" },
+                    wait_seconds: { type: "integer", minimum: 1, maximum: 30, default: 25 },
+                    timeout_seconds: {
+                        type: "integer",
+                        minimum: 1,
+                        maximum: 30,
+                        description: "Preferred alias for wait_seconds. Maximum 30 seconds to stay within connector request limits.",
+                    },
+                },
+                required: ["task_id"],
+            },
+        },
+        {
+            name: "get_task_summary",
+            description: "Return one structured acceptance summary: terminal status, scope violations, verification evidence, changed files, artifact availability, warnings, and errors.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    task_id: { type: "string", description: "Task ID" },
+                },
+                required: ["task_id"],
+            },
+        },
+        {
+            name: "audit_task",
+            description: "Independently audit a task's outputs. Verifies status, result.md, test.log, git.diff, repo_path consistency, cross-references agent claims with package.json scripts, and flags unverified release/publish claims. Writes independent-review.md to the task directory.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    task_id: { type: "string", description: "Task ID to audit" },
+                },
+                required: ["task_id"],
+            },
+        },
+    ];
+    // run_task: only available when explicitly enabled
+    if (config.enableRunTaskTool === true) {
+        tools.push({
+            name: "run_task",
+            description: "Manually trigger execution of a pending task. WARNING: requires enableRunTaskTool=true in config. Prefer using the local watcher instead.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    task_id: { type: "string", description: "Task ID to execute" },
+                },
+                required: ["task_id"],
+            },
+        });
+    }
+    const profile = resolveToolProfile(config.toolProfile);
+    const selected = selectToolsForProfile(tools, profile);
+    buildToolCatalogSnapshot(selected, profile);
+    return selected;
+}
+export function getToolCatalogSnapshot() {
+    const tools = getToolDefs();
+    const config = getConfig();
+    return buildToolCatalogSnapshot(tools, resolveToolProfile(config.toolProfile));
+}
+// ── Request handler ───────────────────────────────────────────────
+export async function handleToolCall(name, args) {
+    switch (name) {
+        case "save_plan": {
+            return toResult(savePlan({
+                title: String(args?.title ?? ""),
+                content: String(args?.content ?? ""),
+            }));
+        }
+        case "get_plan": {
+            return toResult(getPlan({ plan_id: String(args?.plan_id ?? "") }));
+        }
+        case "create_task": {
+            return toResult(createTask({
+                plan_id: args?.plan_id ? String(args.plan_id) : undefined,
+                inline_plan: args?.inline_plan ? String(args.inline_plan) : undefined,
+                plan_title: args?.plan_title ? String(args.plan_title) : undefined,
+                template: args?.template ? String(args.template) : undefined,
+                goal: args?.goal ? String(args.goal) : undefined,
+                source_task_id: args?.source_task_id ? String(args.source_task_id) : undefined,
+                agent: String(args?.agent ?? ""),
+                repo_path: args?.repo_path ? String(args.repo_path) : undefined,
+                test_command: args?.test_command ? String(args.test_command) : undefined,
+                verify_commands: Array.isArray(args?.verify_commands)
+                    ? args.verify_commands.map((command) => String(command))
+                    : undefined,
+                timeout_seconds: args?.timeout_seconds !== undefined
+                    ? Number(args.timeout_seconds)
+                    : undefined,
+            }));
+        }
+        case "get_task_status": {
+            return toResult(getTaskStatus(String(args?.task_id ?? "")));
+        }
+        case "get_result": {
+            return toResult(getResult(String(args?.task_id ?? "")));
+        }
+        case "get_result_json": {
+            return toResult(getResultJson(String(args?.task_id ?? "")));
+        }
+        case "get_diff": {
+            return toResult(getDiff(String(args?.task_id ?? "")));
+        }
+        case "get_test_log": {
+            return toResult(getTestLog(String(args?.task_id ?? "")));
+        }
+        case "list_workspace": {
+            return toResult(listWorkspace(args?.path ? String(args.path) : undefined));
+        }
+        case "read_workspace_file": {
+            return toResult(readWorkspaceFile(String(args?.path ?? "")));
+        }
+        case "list_tasks": {
+            return toResult(listTasks({
+                status: args?.status ? String(args.status) : undefined,
+                repo_path: args?.repo_path ? String(args.repo_path) : undefined,
+                active_only: args?.active_only !== undefined ? Boolean(args.active_only) : undefined,
+                limit: args?.limit ? Number(args.limit) : undefined,
+            }));
+        }
+        case "list_agents": {
+            return toResult(listAgents());
+        }
+        case "health_check": {
+            return toResult(healthCheck(getToolCatalogSnapshot(), {
+                detail: args?.detail === "self_diagnostic" ? "self_diagnostic" : "standard",
+            }));
+        }
+        case "cancel_task": {
+            return toResult(cancelTask(String(args?.task_id ?? "")));
+        }
+        case "kill_task": {
+            return toResult(killTask(String(args?.task_id ?? "")));
+        }
+        case "retry_task": {
+            return toResult(retryTask(String(args?.task_id ?? "")));
+        }
+        case "get_task_stdout_tail": {
+            return toResult(getTaskStdoutTail(String(args?.task_id ?? ""), args?.lines ? Number(args.lines) : undefined));
+        }
+        case "get_task_log_tail": {
+            return toResult(getTaskLogTail(String(args?.task_id ?? ""), args?.file || "stdout", {
+                lines: args?.lines ? Number(args.lines) : undefined,
+                redact: args?.redact !== undefined ? Boolean(args.redact) : undefined,
+            }));
+        }
+        case "get_task_progress": {
+            return toResult(getTaskProgress(String(args?.task_id ?? "")));
+        }
+        case "wait_for_task": {
+            const waitSeconds = normalizeWaitSeconds(args);
+            return toResult(await waitForTask(String(args?.task_id ?? ""), waitSeconds));
+        }
+        case "get_task_summary": {
+            return toResult(getTaskSummary(String(args?.task_id ?? "")));
+        }
+        case "audit_task": {
+            return toResult(auditTask(String(args?.task_id ?? "")));
+        }
+        case "run_task": {
+            const config = getConfig();
+            if (config.enableRunTaskTool !== true) {
+                throw new Error("run_task is disabled. Set enableRunTaskTool: true in config to enable. Prefer using the local watcher (npm run watch).");
+            }
+            const taskId = String(args?.task_id ?? "");
+            const result = await runTask(taskId);
+            return toResult(result);
+        }
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+}
+function normalizeWaitSeconds(args) {
+    const legacy = args?.wait_seconds;
+    const preferred = args?.timeout_seconds;
+    if (legacy !== undefined && preferred !== undefined && Number(legacy) !== Number(preferred)) {
+        throw new Error("wait_seconds and timeout_seconds must match when both are supplied.");
+    }
+    const value = preferred ?? legacy;
+    return value === undefined ? undefined : Number(value);
+}
+function toResult(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+}
+// ── Register on MCP Server ────────────────────────────────────────
+export function registerTools(server) {
+    // Compute the active tool list ONCE to guarantee list/call consistency.
+    // Re-calling getToolDefs() on every request risks divergence between
+    // tools/list and tools/call when the profile is reconfigured at runtime.
+    const activeTools = getToolDefs();
+    const activeNames = new Set(activeTools.map((tool) => tool.name));
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        const catalog = getLastToolCatalogSnapshot();
+        return {
+            tools: activeTools,
+            ...(catalog
+                ? {
+                    _meta: {
+                        server_version: catalog.server_version,
+                        schema_epoch: catalog.schema_epoch,
+                        tool_profile: catalog.tool_profile,
+                        tool_count: catalog.tool_count,
+                        tool_manifest_sha256: catalog.tool_manifest_sha256,
+                    },
+                }
+                : {}),
+        };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        try {
+            if (!activeNames.has(name)) {
+                const catalog = getToolCatalogSnapshot();
+                throw new PatchWardenError("tool_catalog_mismatch", `Tool "${name}" is not available in the active ${catalog.tool_profile} profile. The client may be using a stale tool catalog.`, "Refresh or reconnect the ChatGPT Connector and open a new conversation before retrying.", true, {
+                    requested_tool: name,
+                    refresh_required: true,
+                    server_version: catalog.server_version,
+                    schema_epoch: catalog.schema_epoch,
+                    tool_profile: catalog.tool_profile,
+                    tool_count: catalog.tool_count,
+                    tool_names: catalog.tool_names,
+                    tool_manifest_sha256: catalog.tool_manifest_sha256,
+                    next_tool_call: {
+                        name: "health_check",
+                        arguments: { detail: "self_diagnostic" },
+                    },
+                    connector_refresh_steps: [
+                        "1. Run Check-PatchWarden-Health.cmd locally to confirm the active profile and manifest hash.",
+                        "2. In ChatGPT Platform, refresh or reconnect the Connector (do not reuse an old session).",
+                        "3. Open a NEW ChatGPT conversation; old conversations retain their cached tool catalog.",
+                        "4. Call health_check in the new conversation and verify tool_manifest_sha256 matches the local report.",
+                    ],
+                });
+            }
+            return await handleToolCall(name, args);
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: JSON.stringify(errorPayload(err)) }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/retryTask.d.ts

@@ -0,0 +1,8 @@
+export declare function retryTask(taskId: string): {
+    original_task_id: string;
+    new_task_id: string;
+    plan_id: string;
+    agent: string;
+    status: import("./createTask.js").TaskStatus;
+    message: string;
+};

package/dist/tools/retryTask.js

@@ -0,0 +1,45 @@
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { getTasksDir, getConfig } from "../config.js";
+import { guardReadPath } from "../security/pathGuard.js";
+import { createTask } from "./createTask.js";
+export function retryTask(taskId) {
+    const config = getConfig();
+    const tasksDir = getTasksDir(config);
+    const taskDir = join(tasksDir, taskId);
+    const statusFile = join(taskDir, "status.json");
+    guardReadPath(statusFile, config.workspaceRoot, config.tasksDir);
+    if (!existsSync(statusFile)) {
+        throw new Error(`Task not found: "${taskId}"`);
+    }
+    const data = JSON.parse(readFileSync(statusFile, "utf-8"));
+    if (!data.plan_id || !data.agent) {
+        throw new Error(`Task "${taskId}" is missing plan_id or agent. Cannot retry.`);
+    }
+    // Create a new task with the same parameters
+    const newTask = createTask({
+        plan_id: data.plan_id,
+        agent: data.agent,
+        repo_path: data.repo_path,
+        test_command: data.test_command,
+        verify_commands: data.verify_commands,
+        timeout_seconds: data.timeout_seconds,
+    });
+    // Record retry relationship in the new task
+    const newStatusFile = join(newTask.path, "status.json");
+    const newData = JSON.parse(readFileSync(newStatusFile, "utf-8"));
+    newData.retry_of = taskId;
+    newData.retry_count = (data.retry_count || 0) + 1;
+    newData.plan_source = data.plan_source || "saved";
+    newData.template = data.template || null;
+    newData.change_policy = data.change_policy || "repo_scoped_changes";
+    writeFileSync(newStatusFile, JSON.stringify(newData, null, 2), "utf-8");
+    return {
+        original_task_id: taskId,
+        new_task_id: newTask.task_id,
+        plan_id: newTask.plan_id,
+        agent: newTask.agent,
+        status: newTask.status,
+        message: `New task created from retry of ${taskId}. Original task is unchanged.`,
+    };
+}

package/dist/tools/savePlan.d.ts

@@ -0,0 +1,10 @@
+export interface SavePlanInput {
+    title: string;
+    content: string;
+}
+export interface SavePlanOutput {
+    plan_id: string;
+    path: string;
+    title: string;
+}
+export declare function savePlan(input: SavePlanInput): SavePlanOutput;

package/dist/tools/savePlan.js

@@ -0,0 +1,28 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { getPlansDir, getConfig } from "../config.js";
+import { guardPath } from "../security/pathGuard.js";
+import { guardPlanContent } from "../security/planGuard.js";
+export function savePlan(input) {
+    const config = getConfig();
+    const plansDir = getPlansDir(config);
+    guardPlanContent(input.title, input.content);
+    const planId = `plan_${Date.now()}_${sanitizeTitle(input.title)}`;
+    const planDir = resolve(plansDir, planId);
+    // Guards: plan dir & file must stay inside workspace
+    guardPath(planDir, config.workspaceRoot, config.plansDir);
+    mkdirSync(planDir, { recursive: true });
+    const planFile = join(planDir, "plan.md");
+    const header = `# ${input.title}\n\n> Plan ID: ${planId}\n> Created: ${new Date().toISOString()}\n\n`;
+    writeFileSync(planFile, header + input.content, "utf-8");
+    return {
+        plan_id: planId,
+        path: planFile,
+        title: input.title,
+    };
+}
+function sanitizeTitle(title) {
+    return title
+        .replace(/[^a-zA-Z0-9\u4e00-\u9fff_-]/g, "_")
+        .slice(0, 64);
+}