@unbrained/pm-web 2026.9.13 → 2026.9.23

package/dist/routes/pm.js

@@ -470,12 +470,7 @@ async function pmGraphExtensionGraphForProject(project) {
     if (!provision.ok) {
         return { error: provision.error };
     }
-    const extensionResult = await runPm({
-        args: ["pm-graph", "export", "--json"],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: false,
-    });
+    const extensionResult = await projectPm(project, ["pm-graph", "export", "--json"], false);
     let extensionData;
     if (extensionResult.ok && extensionResult.stdout) {
         try {
@@ -502,16 +497,223 @@ async function verifyProject(userId, projectId) {
         return null;
     return { slug: access.slug, prefix: access.prefix, ownerUserId: access.ownerUserId };
 }
-// GET /api/projects/:projectId/pm/schema
-// Returns runtime types/statuses from `pm contracts --json` so the frontend
-// stays in sync with whatever pm CLI version + extensions are installed.
-router.get("/schema", async (req, res) => {
+/**
+ * Load the caller's project or answer 404.
+ *
+ * The route layer repeats this access check before every pm invocation. One
+ * helper keeps the status and error body identical without copying the lookup.
+ *
+ * @param req - Authenticated request carrying the project id.
+ * @param res - Response used for the not-found body.
+ * @returns The project reference, or undefined after a 404 was sent.
+ */
+async function requireProject(req, res) {
     const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
     if (!project) {
         res.status(404).json({ error: "Project not found" });
+        return undefined;
+    }
+    return project;
+}
+/**
+ * Run pm in the verified project's workspace.
+ *
+ * @param project - Owner and slug that locate the workspace.
+ * @param args - pm arguments, already validated by the route.
+ * @param jsonOutput - When set, request JSON output; omit to keep the CLI default.
+ * @returns The pm invocation result.
+ */
+function projectPm(project, args, jsonOutput) {
+    return runPm({
+        args,
+        userId: project.ownerUserId,
+        slug: project.slug,
+        ...(jsonOutput === undefined ? {} : { jsonOutput }),
+    });
+}
+/**
+ * Shared body of the cursor-paginated list endpoints.
+ *
+ * Copies the base arguments, appends each filter flag whose query value is
+ * present, validates the `after` cursor (sending the shared 400 body when it
+ * is malformed), and maps a USAGE exit to a 400. Returns the command result
+ * so the caller can send its success or failure payload, or `undefined`
+ * after an error response has already been sent.
+ *
+ * @param res - Response used for the cursor and USAGE error bodies.
+ * @param project - Verified project that owns the workspace.
+ * @param baseArgs - Command and fixed arguments; copied, never mutated.
+ * @param flags - Ordered `[flag, value]` pairs appended when `value` is present.
+ * @param after - Raw `after` query value to validate as a pagination cursor.
+ * @returns The pm result, or `undefined` after an error response was sent.
+ */
+async function runCursorList(res, project, baseArgs, flags, after) {
+    const args = [...baseArgs];
+    for (const [flag, value] of flags) {
+        if (value)
+            args.push(flag, value);
+    }
+    const cursorResult = validateCursor(after);
+    if (cursorResult.error) {
+        res.status(400).json({ error: cursorResult.error, items: [] });
+        return undefined;
+    }
+    if (cursorResult.cursor)
+        args.push("--after", cursorResult.cursor);
+    const result = await projectPm(project, args, true);
+    if (!result.ok && result.exitCode === EXIT_CODE.USAGE) {
+        res.status(400).json({ error: result.stderr, items: [] });
+        return undefined;
+    }
+    return result;
+}
+/**
+ * Run a mutating pm command and send the shared failure response.
+ *
+ * Every item and plan mutation maps a failed pm run to
+ * `pmErrorStatus(result)` with `result.stderr || fallback` as the body.
+ * Centralising it keeps the status mapping identical everywhere while the
+ * per-route fallback text stays at the call site.
+ *
+ * @param res - Response used for the failure body.
+ * @param project - Verified project that owns the workspace.
+ * @param args - pm arguments, already validated by the route.
+ * @param fallback - Error text used when pm wrote nothing to stderr.
+ * @param jsonOutput - Request JSON output (default); pass `false` to keep the
+ *   CLI default output, as the raw delete invocation does.
+ * @returns The successful pm result, or `undefined` after the error response.
+ */
+async function runMutation(res, project, args, fallback, jsonOutput = true) {
+    const result = await projectPm(project, args, jsonOutput);
+    if (!result.ok) {
+        res.status(pmErrorStatus(result)).json({ error: result.stderr || fallback });
+        return undefined;
+    }
+    return result;
+}
+/**
+ * Broadcast an item lifecycle event to the project's SSE clients and queue a
+ * graph sync for the same project.
+ *
+ * @param req - Authenticated request carrying the project and user ids.
+ * @param project - Verified project that owns the workspace.
+ * @param type - Event name to broadcast and graph-sync reason.
+ * @param itemId - Item the event is about; defaults to the route's `itemId`.
+ */
+function emitItemEvent(req, project, type, itemId = routeParam(req, "itemId")) {
+    broadcastProjectEvent(routeParam(req, "projectId"), {
+        type,
+        data: { itemId, userId: req.user.userId },
+    });
+    scheduleGraphSync(routeParam(req, "projectId"), project, type);
+}
+/**
+ * Queue a graph sync and broadcast a dependency event for one graph edge.
+ *
+ * The four dependency mutation routes (deps and rel, add and remove) all pair
+ * the same two side effects with the same payload shape; only the sync reason
+ * and the broadcast event name vary between them.
+ *
+ * @param req - Authenticated request carrying the project and user ids.
+ * @param project - Verified project that owns the workspace.
+ * @param syncReason - Graph-sync queue reason for this mutation.
+ * @param event - SSE dependency event name to broadcast.
+ * @param from - Source item id of the edge.
+ * @param to - Target item id of the edge.
+ * @param rel - Dependency kind of the edge.
+ */
+function emitDependencyEvent(req, project, syncReason, event, from, to, rel) {
+    scheduleGraphSync(routeParam(req, "projectId"), project, syncReason);
+    broadcastDependencyEvent(routeParam(req, "projectId"), event, {
+        from,
+        to,
+        rel,
+        userId: req.user.userId,
+    });
+}
+/**
+ * Run a plan mutation and complete the whole response.
+ *
+ * The plan step routes share one response shape end to end: map a failure via
+ * {@link pmErrorStatus} with the per-route fallback text, broadcast an
+ * `item-updated` event naming the plan id, and answer with the parsed result.
+ * This helper performs all of it; the caller supplies only the arguments and
+ * the failure text, and nothing after the call.
+ *
+ * @param req - Authenticated request carrying the project, plan and user ids.
+ * @param res - Response used for both the failure and success bodies.
+ * @param project - Verified project that owns the workspace.
+ * @param args - pm arguments, already validated by the route.
+ * @param fallback - Error text used when pm wrote nothing to stderr.
+ * @param successStatus - HTTP status for the success response (default 200).
+ */
+async function runPlanMutation(req, res, project, args, fallback, successStatus = 200) {
+    const result = await runMutation(res, project, args, fallback);
+    if (!result)
         return;
+    broadcastProjectEvent(routeParam(req, "projectId"), {
+        type: "item-updated",
+        data: { itemId: routeParam(req, "planId"), userId: req.user.userId },
+    });
+    res.status(successStatus).json(result.parsed || {});
+}
+/** Validate a `text` body field and run a mutation with it. Used by the
+ * comments, notes, append and learnings POST routes that all share the same
+ * body shape and error-handling pattern. */
+async function runTextBodyMutation(req, res, project, cmd, errorMsg, failedMsg) {
+    const { text } = req.body;
+    if (!text?.trim()) {
+        res.status(400).json({ error: errorMsg });
+        return undefined;
+    }
+    return runMutation(res, project, [cmd, routeParam(req, "itemId"), text.trim()], failedMsg);
+}
+/** Validate a `reason` body field and run a mutation with it. Used by the
+ * close and close-task POST routes that share the same body shape. */
+async function runReasonBodyMutation(req, res, project, cmd, errorMsg, failedMsg) {
+    const { reason } = req.body;
+    if (!reason?.trim()) {
+        res.status(400).json({ error: errorMsg });
+        return undefined;
+    }
+    return runMutation(res, project, [cmd, routeParam(req, "itemId"), reason.trim()], failedMsg);
+}
+/** Validate the `targetId`/`rel` body fields for deps add/remove routes and
+ * return the normalized dependency kind. */
+function parseDepBody(req, res, defaultRel) {
+    const { targetId, rel } = req.body;
+    if (!targetId?.trim()) {
+        res.status(400).json({ error: "targetId is required" });
+        return undefined;
+    }
+    return { targetId: targetId.trim(), depRel: normalizeDependencyKind(rel || defaultRel) };
+}
+/** Validate the `from`/`to`/`type` body fields for rel add/remove routes and
+ * return the normalized values. */
+function parseRelBody(req, res) {
+    const { from, to, type: relType } = req.body;
+    if (!from?.trim() || !to?.trim()) {
+        res.status(400).json({ error: "from and to item IDs are required" });
+        return undefined;
     }
-    const result = await runPm({ args: ["contracts", "--json"], userId: project.ownerUserId, slug: project.slug, jsonOutput: true });
+    return { from: from.trim(), to: to.trim(), depRel: normalizeDependencyKind(relType || "relates_to") };
+}
+/** Push `--title` and `--description` args from a plan/step PATCH body when
+ * present. Used by the plan and step update routes. */
+function pushTitleDescArgs(args, body) {
+    if (body.title?.trim())
+        args.push("--title", body.title.trim());
+    if (body.description !== undefined)
+        args.push("--description", body.description);
+}
+// GET /api/projects/:projectId/pm/schema
+// Returns runtime types/statuses from `pm contracts --json` so the frontend
+// stays in sync with whatever pm CLI version + extensions are installed.
+router.get("/schema", async (req, res) => {
+    const project = await requireProject(req, res);
+    if (!project)
+        return;
+    const result = await projectPm(project, ["contracts", "--json"], true);
     const contracts = result.ok && result.parsed ? result.parsed : null;
     const rt = contracts?.["runtime_schema"];
     res.json({
@@ -568,11 +770,9 @@ function isSafeTypeFolder(folder) {
  * collaborators with 403 before this handler runs.
  */
 router.post("/schema/add-type", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const body = req.body;
     const name = typeof body.name === "string" ? body.name.trim() : "";
     if (!name) {
@@ -607,7 +807,7 @@ router.post("/schema/add-type", async (req, res) => {
                 args.push("--alias", alias.trim());
         }
     }
-    const result = await runPm({ args, userId: project.ownerUserId, slug: project.slug, jsonOutput: true });
+    const result = await projectPm(project, args, true);
     if (!result.ok) {
         res.status(400).json({ error: result.stderr || "pm schema add-type failed" });
         return;
@@ -623,11 +823,9 @@ router.post("/schema/add-type", async (req, res) => {
  * Dry Run controls against a route that was never mounted.
  */
 router.post("/items/:itemId/history-repair", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const itemId = routeParam(req, "itemId").trim();
     if (!itemId) {
         res.status(400).json({ error: "itemId is required" });
@@ -640,7 +838,7 @@ router.post("/items/:itemId/history-repair", async (req, res) => {
     const args = ["history-repair", itemId];
     if (req.body?.dryRun === true)
         args.push("--dry-run");
-    const result = await runPm({ args, userId: project.ownerUserId, slug: project.slug, jsonOutput: true });
+    const result = await projectPm(project, args, true);
     if (!result.ok) {
         res.status(400).json({ error: result.stderr || "pm history-repair failed" });
         return;
@@ -649,81 +847,48 @@ router.post("/items/:itemId/history-repair", async (req, res) => {
 });
 // GET /api/projects/:projectId/pm/list
 router.get("/list", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const { status, type, limit, priority, sprint, release, assignee, after } = req.query;
-    const args = ["list"];
-    if (status)
-        args.push("--status", status);
-    if (type)
-        args.push("--type", type);
-    if (limit)
-        args.push("--limit", limit);
-    if (priority)
-        args.push("--priority", priority);
-    if (sprint)
-        args.push("--sprint", sprint);
-    if (release)
-        args.push("--release", release);
-    if (assignee)
-        args.push("--assignee", assignee);
-    const cursorResult = validateCursor(after);
-    if (cursorResult.error) {
-        res.status(400).json({ error: cursorResult.error, items: [] });
-        return;
-    }
-    if (cursorResult.cursor)
-        args.push("--after", cursorResult.cursor);
-    const result = await runPm({ args, userId: project.ownerUserId, slug: project.slug, jsonOutput: true });
-    if (!result.ok && result.exitCode === EXIT_CODE.USAGE) {
-        res.status(400).json({ error: result.stderr, items: [] });
+    const result = await runCursorList(res, project, ["list"], [
+        ["--status", status],
+        ["--type", type],
+        ["--limit", limit],
+        ["--priority", priority],
+        ["--sprint", sprint],
+        ["--release", release],
+        ["--assignee", assignee],
+    ], after);
+    if (!result)
         return;
-    }
     res.json(result.ok ? (result.parsed || {}) : { error: result.stderr, items: [] });
 });
 // GET /api/projects/:projectId/pm/list-all
 router.get("/list-all", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const { type, limit, after } = req.query;
     // Preserve the public HTTP compatibility route while invoking the canonical
     // CLI/SDK command internally. This route is intentionally paginated and is
     // therefore distinct from readCompletePmItems used by whole-corpus views.
-    const args = ["list", "--all"];
-    if (type)
-        args.push("--type", type);
-    if (limit)
-        args.push("--limit", limit);
-    const cursorResult = validateCursor(after);
-    if (cursorResult.error) {
-        res.status(400).json({ error: cursorResult.error, items: [] });
-        return;
-    }
-    if (cursorResult.cursor)
-        args.push("--after", cursorResult.cursor);
-    const result = await runPm({ args, userId: project.ownerUserId, slug: project.slug, jsonOutput: true });
-    if (!result.ok && result.exitCode === EXIT_CODE.USAGE) {
-        res.status(400).json({ error: result.stderr, items: [] });
+    const result = await runCursorList(res, project, ["list", "--all"], [
+        ["--type", type],
+        ["--limit", limit],
+    ], after);
+    if (!result)
         return;
-    }
     res.json(result.ok ? (result.parsed || {}) : { error: result.stderr, items: [] });
 });
 // GET /api/projects/:projectId/pm/board
 // Kanban board: items grouped into columns by the workspace's runtime statuses
 // (read live from `pm contracts`) so the board matches the installed CLI.
 router.get("/board", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const contracts = await runPm({ args: ["contracts", "--json"], userId: project.ownerUserId, slug: project.slug, jsonOutput: true });
+    const contracts = await projectPm(project, ["contracts", "--json"], true);
     const rt = contracts.ok && contracts.parsed
         ? contracts.parsed["runtime_schema"]
         : undefined;
@@ -739,11 +904,9 @@ router.get("/board", async (req, res) => {
 // GET /api/projects/:projectId/pm/search?q=...
 // Full-text search over id/title/tags/body via one certified complete read.
 router.get("/search", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const query = String(req.query["q"] ?? "");
     const listed = await readCompletePmItems(project.ownerUserId, project.slug, true);
     if (!listed.ok) {
@@ -755,11 +918,9 @@ router.get("/search", async (req, res) => {
 });
 // POST /api/projects/:projectId/pm/create
 router.post("/create", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const { title, type, priority, description, tags, parent, deadline, assignee, sprint, release, estimate, body, acceptanceCriteria, reporter, component, severity, risk, goal, objective, environment, "blocked-by": blockedBy, "blocked-reason": blockedReason, "repro-steps": reproSteps, "expected-result": expectedResult, "actual-result": actualResult, reviewer, confidence, "why-now": whyNow, value, impact, outcome, "definition-of-ready": definitionOfReady, } = req.body;
     if (!title?.trim()) {
         res.status(400).json({ error: "Title is required" });
@@ -828,7 +989,7 @@ router.post("/create", async (req, res) => {
         args.push("--outcome", outcome);
     if (definitionOfReady)
         args.push("--definition-of-ready", definitionOfReady);
-    const result = await runPm({ args, userId: project.ownerUserId, slug: project.slug, jsonOutput: true });
+    const result = await projectPm(project, args, true);
     if (!result.ok) {
         res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to create item" });
         return;
@@ -843,17 +1004,10 @@ router.post("/create", async (req, res) => {
 });
 // GET /api/projects/:projectId/pm/get/:itemId
 router.get("/get/:itemId", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({
-        args: ["get", routeParam(req, "itemId")],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
+    const result = await projectPm(project, ["get", routeParam(req, "itemId")], true);
     if (!result.ok) {
         res.status(404).json({ error: "Item not found" });
         return;
@@ -870,11 +1024,9 @@ router.get("/get/:itemId", async (req, res) => {
 //   400 — invalid ref, or version/timestamp outside the available history range
 //   404 — unknown item, or item with no recorded history
 router.get("/at/:itemId/:ref", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const itemId = routeParam(req, "itemId");
     const ref = routeParam(req, "ref");
     try {
@@ -912,11 +1064,9 @@ router.get("/at/:itemId/:ref", async (req, res) => {
 });
 // PATCH /api/projects/:projectId/pm/update/:itemId
 router.patch("/update/:itemId", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const body = req.body;
     const args = ["update", routeParam(req, "itemId")];
     // String options
@@ -945,218 +1095,115 @@ router.patch("/update/:itemId", async (req, res) => {
     // Type can be set but must use --type
     if (body.type)
         args.push("--type", body.type);
-    const result = await runPm({ args, userId: project.ownerUserId, slug: project.slug, jsonOutput: true });
-    if (!result.ok) {
-        res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to update item" });
+    const result = await runMutation(res, project, args, "Failed to update item");
+    if (!result)
         return;
-    }
     // Broadcast SSE update event
-    broadcastProjectEvent(routeParam(req, "projectId"), {
-        type: "item-updated",
-        data: { itemId: routeParam(req, "itemId"), userId: req.user.userId },
-    });
-    scheduleGraphSync(routeParam(req, "projectId"), project, "item-updated");
+    emitItemEvent(req, project, "item-updated");
     res.json(result.parsed || {});
 });
 // POST /api/projects/:projectId/pm/close/:itemId
 router.post("/close/:itemId", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
-        return;
-    }
-    const { reason } = req.body;
-    if (!reason?.trim()) {
-        res.status(400).json({ error: "Close reason is required" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({
-        args: ["close", routeParam(req, "itemId"), reason.trim()],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
-    if (!result.ok) {
-        res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to close item" });
+    const result = await runReasonBodyMutation(req, res, project, "close", "Close reason is required", "Failed to close item");
+    if (!result)
         return;
-    }
-    broadcastProjectEvent(routeParam(req, "projectId"), {
-        type: "item-closed",
-        data: { itemId: routeParam(req, "itemId"), userId: req.user.userId },
-    });
-    scheduleGraphSync(routeParam(req, "projectId"), project, "item-closed");
+    emitItemEvent(req, project, "item-closed");
     res.json(result.parsed || {});
 });
 // DELETE /api/projects/:projectId/pm/delete/:itemId
 router.delete("/delete/:itemId", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({
-        args: ["delete", routeParam(req, "itemId"), "--yes"],
-        userId: project.ownerUserId,
-        slug: project.slug,
-    });
-    if (!result.ok) {
-        res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to delete item" });
+    const result = await runMutation(res, project, ["delete", routeParam(req, "itemId"), "--yes"], "Failed to delete item", false);
+    if (!result)
         return;
-    }
-    broadcastProjectEvent(routeParam(req, "projectId"), {
-        type: "item-deleted",
-        data: { itemId: routeParam(req, "itemId"), userId: req.user.userId },
-    });
-    scheduleGraphSync(routeParam(req, "projectId"), project, "item-deleted");
+    emitItemEvent(req, project, "item-deleted");
     res.json({ ok: true });
 });
 // POST /api/projects/:projectId/pm/comments/:itemId
 router.post("/comments/:itemId", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
-        return;
-    }
-    const { text } = req.body;
-    if (!text?.trim()) {
-        res.status(400).json({ error: "Comment text is required" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({
-        args: ["comments", routeParam(req, "itemId"), text.trim()],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
-    if (!result.ok) {
-        res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to add comment" });
+    const result = await runTextBodyMutation(req, res, project, "comments", "Comment text is required", "Failed to add comment");
+    if (!result)
         return;
-    }
     res.status(201).json(result.parsed || { ok: true });
 });
 // GET /api/projects/:projectId/pm/comments/:itemId
 router.get("/comments/:itemId", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({
-        args: ["comments", routeParam(req, "itemId")],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
+    const result = await projectPm(project, ["comments", routeParam(req, "itemId")], true);
     res.json(result.ok ? (result.parsed || {}) : { comments: [] });
 });
 // GET /api/projects/:projectId/pm/notes/:itemId
 router.get("/notes/:itemId", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({
-        args: ["notes", routeParam(req, "itemId")],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
+    const result = await projectPm(project, ["notes", routeParam(req, "itemId")], true);
     res.json(result.ok ? (result.parsed || {}) : { notes: [] });
 });
 // POST /api/projects/:projectId/pm/notes/:itemId
 router.post("/notes/:itemId", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
-        return;
-    }
-    const { text } = req.body;
-    if (!text?.trim()) {
-        res.status(400).json({ error: "Note text is required" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({
-        args: ["notes", routeParam(req, "itemId"), text.trim()],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
-    if (!result.ok) {
-        res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to add note" });
+    const result = await runTextBodyMutation(req, res, project, "notes", "Note text is required", "Failed to add note");
+    if (!result)
         return;
-    }
     res.status(201).json(result.parsed || { ok: true });
 });
 // GET /api/projects/:projectId/pm/context
 router.get("/context", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const { depth } = req.query;
     const validDepths = ["brief", "standard", "deep"];
     const resolvedDepth = validDepths.includes(depth) ? depth : "standard";
-    const result = await runPm({
-        args: ["context", "--depth", resolvedDepth],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
+    const result = await projectPm(project, ["context", "--depth", resolvedDepth], true);
     res.json(result.ok ? (result.parsed || {}) : { error: result.stderr });
 });
 // GET /api/projects/:projectId/pm/activity
 router.get("/activity", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const { limit } = req.query;
     const args = ["activity"];
     if (limit)
         args.push("--limit", limit);
-    const result = await runPm({ args, userId: project.ownerUserId, slug: project.slug, jsonOutput: true });
+    const result = await projectPm(project, args, true);
     res.json(result.ok ? (result.parsed || {}) : { activity: [] });
 });
 // GET /api/projects/:projectId/pm/stats
 router.get("/stats", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({
-        args: ["stats"],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
+    const result = await projectPm(project, ["stats"], true);
     res.json(result.ok ? (result.parsed || {}) : { error: result.stderr });
 });
 // GET /api/projects/:projectId/pm/aggregate
 router.get("/aggregate", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({
-        args: ["aggregate"],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
+    const result = await projectPm(project, ["aggregate"], true);
     res.json(result.ok ? (result.parsed || {}) : { error: result.stderr });
 });
 // POST /api/projects/:projectId/pm/search
 router.post("/search", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const body = req.body;
     const query = typeof body["query"] === "string" ? body["query"] : "";
     const mode = typeof body["mode"] === "string" ? body["mode"] : "";
@@ -1184,12 +1231,7 @@ router.post("/search", async (req, res) => {
     if (cursorResult.cursor)
         args.push("--after", cursorResult.cursor);
     args.push("--", ...query.trim().split(/\s+/));
-    const result = await runPm({
-        args,
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
+    const result = await projectPm(project, args, true);
     if (!result.ok) {
         res.status(pmErrorStatus(result)).json({
             error: result.stderr || "Search failed. Check that Ollama is reachable and the configured embedding model is available.",
@@ -1201,17 +1243,10 @@ router.post("/search", async (req, res) => {
 });
 // GET /api/projects/:projectId/pm/calendar
 router.get("/calendar", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({
-        args: ["calendar", "--view", "month"],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
+    const result = await projectPm(project, ["calendar", "--view", "month"], true);
     res.json(result.ok ? (result.parsed || {}) : { events: [] });
 });
 // GET /api/projects/:projectId/pm/calendar.ics
@@ -1220,11 +1255,9 @@ router.get("/calendar", async (req, res) => {
 // Auth works via the usual token (header/cookie) or a
 // `?token=` query param, since calendar clients cannot send cookies.
 router.get("/calendar.ics", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const listed = await readCompletePmItems(project.ownerUserId, project.slug);
     if (!listed.ok) {
         res.status(502).json({ error: listed.stderr || "Failed to load items" });
@@ -1253,211 +1286,102 @@ router.get("/calendar.ics", async (req, res) => {
 });
 // GET /api/projects/:projectId/pm/health
 router.get("/health", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({
-        args: ["health"],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
+    const result = await projectPm(project, ["health"], true);
     res.json(result.ok ? (result.parsed || {}) : { error: result.stderr });
 });
 // POST /api/projects/:projectId/pm/append/:itemId
 router.post("/append/:itemId", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const { text } = req.body;
-    if (!text?.trim()) {
-        res.status(400).json({ error: "Text is required" });
+    const result = await runTextBodyMutation(req, res, project, "append", "Text is required", "Failed to append");
+    if (!result)
         return;
-    }
-    const result = await runPm({
-        args: ["append", routeParam(req, "itemId"), text.trim()],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
-    if (!result.ok) {
-        res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to append" });
-        return;
-    }
     scheduleGraphSync(routeParam(req, "projectId"), project, "item-appended");
     res.json(result.parsed || { ok: true });
 });
 // GET /api/projects/:projectId/pm/history/:itemId
 router.get("/history/:itemId", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({
-        args: ["history", routeParam(req, "itemId")],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
+    const result = await projectPm(project, ["history", routeParam(req, "itemId")], true);
     res.json(result.ok ? (result.parsed || {}) : { history: [] });
 });
 // GET /api/projects/:projectId/pm/deps/:itemId
 router.get("/deps/:itemId", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({
-        args: ["deps", routeParam(req, "itemId")],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
+    const result = await projectPm(project, ["deps", routeParam(req, "itemId")], true);
     res.json(result.ok ? (result.parsed || {}) : { deps: [] });
 });
 // POST /api/projects/:projectId/pm/deps/:itemId
 router.post("/deps/:itemId", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const { targetId, rel } = req.body;
-    if (!targetId?.trim()) {
-        res.status(400).json({ error: "targetId is required" });
+    const dep = parseDepBody(req, res);
+    if (!dep)
         return;
-    }
-    const depRel = normalizeDependencyKind(rel);
-    const result = await runPm({
-        args: ["update", routeParam(req, "itemId"), "--dep", `id=${targetId.trim()},kind=${depRel}`],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
-    if (!result.ok) {
-        res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to add dependency" });
+    const result = await runMutation(res, project, ["update", routeParam(req, "itemId"), "--dep", `id=${dep.targetId},kind=${dep.depRel}`], "Failed to add dependency");
+    if (!result)
         return;
-    }
-    scheduleGraphSync(routeParam(req, "projectId"), project, "dependency-added");
-    broadcastDependencyEvent(routeParam(req, "projectId"), "dependency-added", {
-        from: routeParam(req, "itemId"),
-        to: targetId.trim(),
-        rel: depRel,
-        userId: req.user.userId,
-    });
+    emitDependencyEvent(req, project, "dependency-added", "dependency-added", routeParam(req, "itemId"), dep.targetId, dep.depRel);
     res.status(201).json(result.parsed || { ok: true });
 });
 // DELETE /api/projects/:projectId/pm/deps/:itemId
 router.delete("/deps/:itemId", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const { targetId, rel } = req.body;
-    if (!targetId?.trim()) {
-        res.status(400).json({ error: "targetId is required" });
+    const dep = parseDepBody(req, res, "relates_to");
+    if (!dep)
         return;
-    }
-    const depRel = normalizeDependencyKind(rel || "relates_to");
-    const selector = `id=${targetId.trim()},kind=${depRel}`;
-    const result = await runPm({
-        args: ["update", routeParam(req, "itemId"), "--dep-remove", selector],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
-    if (!result.ok) {
-        res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to remove dependency" });
+    const selector = `id=${dep.targetId},kind=${dep.depRel}`;
+    const result = await runMutation(res, project, ["update", routeParam(req, "itemId"), "--dep-remove", selector], "Failed to remove dependency");
+    if (!result)
         return;
-    }
-    scheduleGraphSync(routeParam(req, "projectId"), project, "dependency-removed");
-    broadcastDependencyEvent(routeParam(req, "projectId"), "dependency-removed", {
-        from: routeParam(req, "itemId"),
-        to: targetId.trim(),
-        rel: depRel,
-        userId: req.user.userId,
-    });
-    res.status(200).json({ ok: true, from: routeParam(req, "itemId"), to: targetId.trim(), type: depRel, result: result.parsed || null });
+    emitDependencyEvent(req, project, "dependency-removed", "dependency-removed", routeParam(req, "itemId"), dep.targetId, dep.depRel);
+    res.status(200).json({ ok: true, from: routeParam(req, "itemId"), to: dep.targetId, type: dep.depRel, result: result.parsed || null });
 });
 // POST /api/projects/:projectId/pm/rel — Create a relationship between two items
 router.post("/rel", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const { from, to, type: relType } = req.body;
-    if (!from?.trim() || !to?.trim()) {
-        res.status(400).json({ error: "from and to item IDs are required" });
+    const rel = parseRelBody(req, res);
+    if (!rel)
         return;
-    }
-    const depRel = normalizeDependencyKind(relType || "relates_to");
-    const result = await runPm({
-        args: ["update", from.trim(), "--dep", `id=${to.trim()},kind=${depRel}`],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
-    if (!result.ok) {
-        res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to create relationship" });
+    const result = await runMutation(res, project, ["update", rel.from, "--dep", `id=${rel.to},kind=${rel.depRel}`], "Failed to create relationship");
+    if (!result)
         return;
-    }
-    scheduleGraphSync(routeParam(req, "projectId"), project, "rel-created");
-    broadcastDependencyEvent(routeParam(req, "projectId"), "dependency-added", {
-        from: from.trim(),
-        to: to.trim(),
-        rel: depRel,
-        userId: req.user.userId,
-    });
-    res.status(201).json({ ok: true, from: from.trim(), to: to.trim(), type: depRel });
+    emitDependencyEvent(req, project, "rel-created", "dependency-added", rel.from, rel.to, rel.depRel);
+    res.status(201).json({ ok: true, from: rel.from, to: rel.to, type: rel.depRel });
 });
 // DELETE /api/projects/:projectId/pm/rel — Remove a relationship between two items
 router.delete("/rel", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const { from, to, type: relType } = req.body;
-    if (!from?.trim() || !to?.trim()) {
-        res.status(400).json({ error: "from and to item IDs are required" });
+    const rel = parseRelBody(req, res);
+    if (!rel)
         return;
-    }
-    const depRel = normalizeDependencyKind(relType || "relates_to");
-    const selector = `id=${to.trim()},kind=${depRel}`;
-    const result = await runPm({
-        args: ["update", from.trim(), "--dep-remove", selector, "--message", `Remove ${depRel} dependency on ${to.trim()}`],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
-    if (!result.ok) {
-        res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to remove relationship" });
+    const selector = `id=${rel.to},kind=${rel.depRel}`;
+    const result = await runMutation(res, project, ["update", rel.from, "--dep-remove", selector, "--message", `Remove ${rel.depRel} dependency on ${rel.to}`], "Failed to remove relationship");
+    if (!result)
         return;
-    }
-    scheduleGraphSync(routeParam(req, "projectId"), project, "rel-removed");
-    broadcastDependencyEvent(routeParam(req, "projectId"), "dependency-removed", {
-        from: from.trim(),
-        to: to.trim(),
-        rel: depRel,
-        userId: req.user.userId,
-    });
-    res.json({ ok: true, from: from.trim(), to: to.trim(), type: depRel, result: result.parsed || null });
+    emitDependencyEvent(req, project, "rel-removed", "dependency-removed", rel.from, rel.to, rel.depRel);
+    res.json({ ok: true, from: rel.from, to: rel.to, type: rel.depRel, result: result.parsed || null });
 });
 // GET /api/projects/:projectId/pm/graph
 router.get("/graph", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const extensionGraph = await pmGraphExtensionGraphForProject(project);
     if (extensionGraph.graph) {
         res.json({
@@ -1481,11 +1405,9 @@ router.get("/graph", async (req, res) => {
 });
 // POST /api/projects/:projectId/pm/graph/sync
 router.post("/graph/sync", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     try {
         const syncResult = await syncProjectGraph(project);
         const payload = { reason: "manual-sync", ...syncResult, projectKey: graphProjectKey(project), source: "pm-web" };
@@ -1515,22 +1437,15 @@ router.post("/graph/sync", async (req, res) => {
 });
 // GET /api/projects/:projectId/pm/graph/neighbors/:nodeId
 router.get("/graph/neighbors/:nodeId", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const nodeId = routeParam(req, "nodeId");
     if (!nodeId) {
         res.status(400).json({ error: "nodeId is required" });
         return;
     }
-    const result = await runPm({
-        args: ["pm-graph", "neighbors", nodeId, "--json"],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: false,
-    });
+    const result = await projectPm(project, ["pm-graph", "neighbors", nodeId, "--json"], false);
     if (!result.ok) {
         // Extension not available — return empty neighbors
         res.json({ ok: true, center: null, neighbors: [], extensionAvailable: false, error: result.stderr || "pm-graph extension not available" });
@@ -1546,22 +1461,15 @@ router.get("/graph/neighbors/:nodeId", async (req, res) => {
 });
 // POST /api/projects/:projectId/pm/graph/query
 router.post("/graph/query", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const { cypher } = req.body;
     if (!cypher?.trim()) {
         res.status(400).json({ error: "cypher query is required" });
         return;
     }
-    const result = await runPm({
-        args: ["pm-graph", "query", cypher.trim(), "--json"],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: false,
-    });
+    const result = await projectPm(project, ["pm-graph", "query", cypher.trim(), "--json"], false);
     if (!result.ok) {
         res.status(pmErrorStatus(result)).json({ error: result.stderr || "pm-graph query failed — ensure Neo4j is configured and pm-graph extension is installed" });
         return;
@@ -1576,145 +1484,79 @@ router.post("/graph/query", async (req, res) => {
 });
 // GET /api/projects/:projectId/pm/learnings/:itemId
 router.get("/learnings/:itemId", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({
-        args: ["learnings", routeParam(req, "itemId")],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
+    const result = await projectPm(project, ["learnings", routeParam(req, "itemId")], true);
     res.json(result.ok ? (result.parsed || {}) : { learnings: [] });
 });
 // POST /api/projects/:projectId/pm/learnings/:itemId
 router.post("/learnings/:itemId", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const { text } = req.body;
-    if (!text?.trim()) {
-        res.status(400).json({ error: "Learning text is required" });
+    const result = await runTextBodyMutation(req, res, project, "learnings", "Learning text is required", "Failed to add learning");
+    if (!result)
         return;
-    }
-    const result = await runPm({
-        args: ["learnings", routeParam(req, "itemId"), text.trim()],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
-    if (!result.ok) {
-        res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to add learning" });
-        return;
-    }
     res.status(201).json(result.parsed || { ok: true });
 });
 // POST /api/projects/:projectId/pm/claim/:itemId
 router.post("/claim/:itemId", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({
-        args: ["claim", routeParam(req, "itemId")],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
-    if (!result.ok) {
-        res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to claim item" });
+    const result = await runMutation(res, project, ["claim", routeParam(req, "itemId")], "Failed to claim item");
+    if (!result)
         return;
-    }
     scheduleGraphSync(routeParam(req, "projectId"), project, "item-claimed");
     res.json(result.parsed || { ok: true });
 });
 // POST /api/projects/:projectId/pm/release/:itemId
 router.post("/release/:itemId", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({
-        args: ["release", routeParam(req, "itemId")],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
-    if (!result.ok) {
-        res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to release item" });
+    const result = await runMutation(res, project, ["release", routeParam(req, "itemId")], "Failed to release item");
+    if (!result)
         return;
-    }
     scheduleGraphSync(routeParam(req, "projectId"), project, "item-released");
     res.json(result.parsed || { ok: true });
 });
 // POST /api/projects/:projectId/pm/start-task/:itemId
 router.post("/start-task/:itemId", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({
-        args: ["start-task", routeParam(req, "itemId")],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
-    if (!result.ok) {
-        res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to start task" });
+    const result = await runMutation(res, project, ["start-task", routeParam(req, "itemId")], "Failed to start task");
+    if (!result)
         return;
-    }
     scheduleGraphSync(routeParam(req, "projectId"), project, "task-started");
     res.json(result.parsed || { ok: true });
 });
 // POST /api/projects/:projectId/pm/pause-task/:itemId
 router.post("/pause-task/:itemId", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({
-        args: ["pause-task", routeParam(req, "itemId")],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
-    if (!result.ok) {
-        res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to pause task" });
+    const result = await runMutation(res, project, ["pause-task", routeParam(req, "itemId")], "Failed to pause task");
+    if (!result)
         return;
-    }
     scheduleGraphSync(routeParam(req, "projectId"), project, "task-paused");
     res.json(result.parsed || { ok: true });
 });
 // GET /api/projects/:projectId/pm/tests/:itemId
 router.get("/tests/:itemId", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({
-        args: ["test", routeParam(req, "itemId")],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
+    const result = await projectPm(project, ["test", routeParam(req, "itemId")], true);
     res.json(result.ok ? (result.parsed || {}) : { tests: [] });
 });
 // POST /api/projects/:projectId/pm/tests/:itemId
 router.post("/tests/:itemId", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const { command, description } = req.body;
     if (!command?.trim()) {
         res.status(400).json({ error: "Test command is required" });
@@ -1723,113 +1565,63 @@ router.post("/tests/:itemId", async (req, res) => {
     const args = ["test", routeParam(req, "itemId"), "--add", "--command", command.trim()];
     if (description)
         args.push("--description", description.trim());
-    const result = await runPm({
-        args,
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
-    if (!result.ok) {
-        res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to add test" });
+    const result = await runMutation(res, project, args, "Failed to add test");
+    if (!result)
         return;
-    }
     res.status(201).json(result.parsed || { ok: true });
 });
 // GET /api/projects/:projectId/pm/dedupe-audit
 router.get("/dedupe-audit", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({
-        args: ["dedupe-audit"],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
+    const result = await projectPm(project, ["dedupe-audit"], true);
     res.json(result.ok ? (result.parsed || {}) : { duplicates: [] });
 });
 // GET /api/projects/:projectId/pm/validate
 router.get("/validate", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({
-        args: ["validate"],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
+    const result = await projectPm(project, ["validate"], true);
     res.json(result.ok ? (result.parsed || {}) : { error: result.stderr });
 });
 // POST /api/projects/:projectId/pm/restore/:itemId
 router.post("/restore/:itemId", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const { target } = req.body;
     if (!target?.trim()) {
         res.status(400).json({ error: "Restore target (timestamp or version) is required" });
         return;
     }
-    const result = await runPm({
-        args: ["restore", routeParam(req, "itemId"), target.trim()],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
-    if (!result.ok) {
-        res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to restore item" });
+    const result = await runMutation(res, project, ["restore", routeParam(req, "itemId"), target.trim()], "Failed to restore item");
+    if (!result)
         return;
-    }
     scheduleGraphSync(routeParam(req, "projectId"), project, "item-restored");
     res.json(result.parsed || { ok: true });
 });
 // POST /api/projects/:projectId/pm/close-task/:itemId
 router.post("/close-task/:itemId", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const { reason } = req.body;
-    if (!reason?.trim()) {
-        res.status(400).json({ error: "Close reason is required" });
-        return;
-    }
-    const result = await runPm({
-        args: ["close-task", routeParam(req, "itemId"), reason.trim()],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
-    if (!result.ok) {
-        res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to close task" });
+    const result = await runReasonBodyMutation(req, res, project, "close-task", "Close reason is required", "Failed to close task");
+    if (!result)
         return;
-    }
     scheduleGraphSync(routeParam(req, "projectId"), project, "task-closed");
     res.json(result.parsed || { ok: true });
 });
 // POST /api/projects/:projectId/pm/reindex
 router.post("/reindex", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const { mode = "keyword" } = req.body;
     const validModes = ["keyword", "semantic", "hybrid"];
     const safeMode = validModes.includes(mode) ? mode : "keyword";
-    const result = await runPm({
-        args: ["reindex", "--mode", safeMode],
-        userId: project.ownerUserId,
-        slug: project.slug,
-    });
+    const result = await projectPm(project, ["reindex", "--mode", safeMode]);
     if (!result.ok) {
         res.status(400).json({
             error: result.stderr || "Reindex failed. Check that Ollama is reachable and the configured embedding model is available.",
@@ -1840,41 +1632,25 @@ router.post("/reindex", async (req, res) => {
 });
 // POST /api/projects/:projectId/pm/normalize
 router.post("/normalize", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({
-        args: ["normalize"],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
+    const result = await projectPm(project, ["normalize"], true);
     res.json(result.ok ? (result.parsed || {}) : { error: result.stderr });
 });
 // GET /api/projects/:projectId/pm/comments-audit
 router.get("/comments-audit", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({
-        args: ["comments-audit"],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
+    const result = await projectPm(project, ["comments-audit"], true);
     res.json(result.ok ? (result.parsed || {}) : { error: result.stderr });
 });
 // POST /api/projects/:projectId/pm/files/:itemId
 router.post("/files/:itemId", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const { path: filePath, scope } = req.body;
     if (!filePath?.trim()) {
         res.status(400).json({ error: "File path is required" });
@@ -1884,62 +1660,34 @@ router.post("/files/:itemId", async (req, res) => {
     if (scope)
         addVal += `,scope=${scope}`;
     const args = ["files", routeParam(req, "itemId"), "--add", addVal];
-    const result = await runPm({
-        args,
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
-    if (!result.ok) {
-        res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to link file" });
+    const result = await runMutation(res, project, args, "Failed to link file");
+    if (!result)
         return;
-    }
     scheduleGraphSync(routeParam(req, "projectId"), project, "file-linked");
     res.status(201).json(result.parsed || { ok: true });
 });
 // GET /api/projects/:projectId/pm/files/:itemId
 router.get("/files/:itemId", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({
-        args: ["files", routeParam(req, "itemId")],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
+    const result = await projectPm(project, ["files", routeParam(req, "itemId")], true);
     res.json(result.ok ? (result.parsed || {}) : { files: [] });
 });
 // GET /api/projects/:projectId/pm/guide — list guide topics
-router.get("/guide", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+router.get("/guide", async (req, res) => {
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({
-        args: ["guide"],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
+    const result = await projectPm(project, ["guide"], true);
     res.json(result.ok ? (result.parsed || {}) : { error: result.stderr });
 });
 // GET /api/projects/:projectId/pm/guide/:topicId — get single guide topic
 router.get("/guide/:topicId", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({
-        args: ["guide", routeParam(req, "topicId")],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
+    const result = await projectPm(project, ["guide", routeParam(req, "topicId")], true);
     if (!result.ok) {
         res.status(404).json({ error: result.stderr || "Topic not found" });
         return;
@@ -1953,11 +1701,9 @@ router.get("/guide/:topicId", async (req, res) => {
 // ─────────────────────────────────────────────────────────
 // GET /api/projects/:projectId/pm/export?format=json|csv|yaml
 router.get("/export", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const format = req.query["format"] || "json";
     const result = await readCompletePmItems(project.ownerUserId, project.slug, true);
     if (!result.ok) {
@@ -2047,11 +1793,9 @@ router.get("/export", async (req, res) => {
 });
 // POST /api/projects/:projectId/pm/import — import JSON items
 router.post("/import", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const { items } = req.body;
     if (!items || !Array.isArray(items) || items.length === 0) {
         res.status(400).json({ error: "items array is required" });
@@ -2094,7 +1838,7 @@ router.post("/import", async (req, res) => {
             args.push("--body", item.body);
         if (item.parent)
             args.push("--parent", item.parent);
-        const result = await runPm({ args, userId: project.ownerUserId, slug: project.slug, jsonOutput: true });
+        const result = await projectPm(project, args, true);
         if (result.ok && result.parsed) {
             // `pm create --json` (and the in-process SDK dispatcher) return the flat
             // envelope { id, status, changed_field_count } — no `item` wrapper.
@@ -2115,11 +1859,9 @@ router.post("/import", async (req, res) => {
 });
 // POST /api/projects/:projectId/pm/update-many
 router.post("/update-many", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const body = req.body;
     const args = ["update-many"];
     // Filter options
@@ -2153,7 +1895,7 @@ router.post("/update-many", async (req, res) => {
         if (body[key])
             args.push(flag, body[key]);
     }
-    const result = await runPm({ args, userId: project.ownerUserId, slug: project.slug, jsonOutput: true });
+    const result = await projectPm(project, args, true);
     if (!result.ok) {
         res.status(pmErrorStatus(result)).json({ error: result.stderr || "update-many failed" });
         return;
@@ -2170,11 +1912,9 @@ router.post("/update-many", async (req, res) => {
 // Accepts same filter options as update-many plus a required `reason` field.
 // Returns { closed_count, failed_count, skipped_count, rows }.
 router.post("/close-many", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const body = req.body;
     const reason = body.reason?.trim();
     if (!reason) {
@@ -2195,7 +1935,7 @@ router.post("/close-many", async (req, res) => {
         if (body[key])
             listArgs.push(flag, body[key]);
     }
-    const listResult = await runPm({ args: listArgs, userId: project.ownerUserId, slug: project.slug, jsonOutput: true });
+    const listResult = await projectPm(project, listArgs, true);
     if (!listResult.ok) {
         res.status(pmErrorStatus(listResult)).json({ error: listResult.stderr || "Failed to list items for close-many" });
         return;
@@ -2215,7 +1955,7 @@ router.post("/close-many", async (req, res) => {
         const closeArgs = targetStatus === "canceled"
             ? ["update", itemId, "--status", "canceled"]
             : ["close", itemId, reason];
-        const closeResult = await runPm({ args: closeArgs, userId: project.ownerUserId, slug: project.slug, jsonOutput: true });
+        const closeResult = await projectPm(project, closeArgs, true);
         if (closeResult.ok) {
             rows.push({ id: itemId, status: "ok" });
             closedCount++;
@@ -2242,26 +1982,17 @@ router.post("/close-many", async (req, res) => {
 });
 // GET /api/projects/:projectId/pm/docs/:itemId
 router.get("/docs/:itemId", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({
-        args: ["docs", routeParam(req, "itemId")],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
+    const result = await projectPm(project, ["docs", routeParam(req, "itemId")], true);
     res.json(result.ok ? (result.parsed || {}) : { docs: [] });
 });
 // POST /api/projects/:projectId/pm/docs/:itemId
 router.post("/docs/:itemId", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const { path: docPath, scope, note, remove, validatePaths } = req.body;
     const args = ["docs", routeParam(req, "itemId")];
     if (remove) {
@@ -2282,7 +2013,7 @@ router.post("/docs/:itemId", async (req, res) => {
         res.status(400).json({ error: "path, remove, or validatePaths is required" });
         return;
     }
-    const result = await runPm({ args, userId: project.ownerUserId, slug: project.slug, jsonOutput: true });
+    const result = await projectPm(project, args, true);
     if (!result.ok) {
         res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to update docs" });
         return;
@@ -2292,11 +2023,9 @@ router.post("/docs/:itemId", async (req, res) => {
 });
 // POST /api/projects/:projectId/pm/test-all
 router.post("/test-all", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const body = req.body;
     const args = ["test-all"];
     if (body.status)
@@ -2305,7 +2034,7 @@ router.post("/test-all", async (req, res) => {
         args.push("--limit", body.limit);
     if (body.timeout)
         args.push("--timeout", body.timeout);
-    const result = await runPm({ args, userId: project.ownerUserId, slug: project.slug, jsonOutput: true });
+    const result = await projectPm(project, args, true);
     if (!result.ok) {
         res.status(pmErrorStatus(result)).json({ error: result.stderr || "test-all failed" });
         return;
@@ -2314,78 +2043,64 @@ router.post("/test-all", async (req, res) => {
 });
 // GET /api/projects/:projectId/pm/test-runs
 router.get("/test-runs", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const { status, limit } = req.query;
     const args = ["test-runs", "list"];
     if (status)
         args.push("--status", status);
     if (limit)
         args.push("--limit", limit);
-    const result = await runPm({ args, userId: project.ownerUserId, slug: project.slug, jsonOutput: true });
+    const result = await projectPm(project, args, true);
     res.json(result.ok ? (result.parsed || {}) : { runs: [] });
 });
 // POST /api/projects/:projectId/pm/gc
 router.post("/gc", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({ args: ["gc"], userId: project.ownerUserId, slug: project.slug, jsonOutput: true });
+    const result = await projectPm(project, ["gc"], true);
     res.json(result.ok ? (result.parsed || {}) : { error: result.stderr });
 });
 // GET /api/projects/:projectId/pm/templates
 router.get("/templates", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({ args: ["templates", "list"], userId: project.ownerUserId, slug: project.slug, jsonOutput: true });
+    const result = await projectPm(project, ["templates", "list"], true);
     res.json(result.ok ? (result.parsed || {}) : { templates: [] });
 });
 // GET /api/projects/:projectId/pm/templates/:name
 router.get("/templates/:name", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({ args: ["templates", "show", routeParam(req, "name")], userId: project.ownerUserId, slug: project.slug, jsonOutput: true });
+    const result = await projectPm(project, ["templates", "show", routeParam(req, "name")], true);
     res.json(result.ok ? (result.parsed || {}) : { error: result.stderr });
 });
 // GET /api/projects/:projectId/pm/config
 router.get("/config", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({ args: ["config", "project", "list"], userId: project.ownerUserId, slug: project.slug, jsonOutput: true });
+    const result = await projectPm(project, ["config", "project", "list"], true);
     res.json(result.ok ? (result.parsed || {}) : { error: result.stderr });
 });
 // GET /api/projects/:projectId/pm/config/:key
 router.get("/config/:key", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const key = routeParam(req, "key");
-    const result = await runPm({ args: ["config", "project", "get", key], userId: project.ownerUserId, slug: project.slug, jsonOutput: true });
+    const result = await projectPm(project, ["config", "project", "get", key], true);
     res.json(result.ok ? (result.parsed || {}) : { error: result.stderr });
 });
 // PATCH /api/projects/:projectId/pm/config/:key
 router.patch("/config/:key", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const key = routeParam(req, "key");
     const body = req.body;
     const args = ["config", "project", "set", key];
@@ -2395,7 +2110,7 @@ router.patch("/config/:key", async (req, res) => {
         args.push("--policy", body.policy);
     if (body.format)
         args.push("--format", body.format);
-    const result = await runPm({ args, userId: project.ownerUserId, slug: project.slug, jsonOutput: true });
+    const result = await projectPm(project, args, true);
     res.json(result.ok ? (result.parsed || {}) : { error: result.stderr });
 });
 // ─── List status shortcut routes ───
@@ -2414,41 +2129,22 @@ router.patch("/config/:key", async (req, res) => {
  */
 function buildListShortcutRoute(pmCommand) {
     return async (req, res) => {
-        const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-        if (!project) {
-            res.status(404).json({ error: "Project not found" });
+        const project = await requireProject(req, res);
+        if (!project)
             return;
-        }
         const { type, limit, offset, tag, priority, assignee, sprint, release, after } = req.query;
-        const args = [pmCommand];
-        if (type)
-            args.push("--type", type);
-        if (limit)
-            args.push("--limit", limit);
-        if (offset)
-            args.push("--offset", offset);
-        if (tag)
-            args.push("--tag", tag);
-        if (priority)
-            args.push("--priority", priority);
-        if (assignee)
-            args.push("--assignee", assignee);
-        if (sprint)
-            args.push("--sprint", sprint);
-        if (release)
-            args.push("--release", release);
-        const cursorResult = validateCursor(after);
-        if (cursorResult.error) {
-            res.status(400).json({ error: cursorResult.error, items: [] });
-            return;
-        }
-        if (cursorResult.cursor)
-            args.push("--after", cursorResult.cursor);
-        const result = await runPm({ args, userId: project.ownerUserId, slug: project.slug, jsonOutput: true });
-        if (!result.ok && result.exitCode === EXIT_CODE.USAGE) {
-            res.status(400).json({ error: result.stderr, items: [] });
+        const result = await runCursorList(res, project, [pmCommand], [
+            ["--type", type],
+            ["--limit", limit],
+            ["--offset", offset],
+            ["--tag", tag],
+            ["--priority", priority],
+            ["--assignee", assignee],
+            ["--sprint", sprint],
+            ["--release", release],
+        ], after);
+        if (!result)
             return;
-        }
         res.json(result.ok ? (result.parsed || {}) : { items: [] });
     };
 }
@@ -2463,11 +2159,9 @@ router.get("/list-canceled", buildListShortcutRoute("list-canceled"));
 // ─────────────────────────────────────────────────────────
 // POST /api/projects/:projectId/pm/plan
 router.post("/plan", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const { title, description, scope, tags, priority, body } = req.body;
     if (!title?.trim()) {
         res.status(400).json({ error: "Title is required" });
@@ -2484,7 +2178,7 @@ router.post("/plan", async (req, res) => {
         args.push("--priority", priority);
     if (body)
         args.push("--body", body);
-    const result = await runPm({ args, userId: project.ownerUserId, slug: project.slug, jsonOutput: true });
+    const result = await projectPm(project, args, true);
     if (!result.ok) {
         res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to create plan" });
         return;
@@ -2497,17 +2191,10 @@ router.post("/plan", async (req, res) => {
 });
 // GET /api/projects/:projectId/pm/plan/:planId
 router.get("/plan/:planId", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({
-        args: ["plan", "show", routeParam(req, "planId"), "--depth", "standard"],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
+    const result = await projectPm(project, ["plan", "show", routeParam(req, "planId"), "--depth", "standard"], true);
     if (!result.ok) {
         res.status(404).json({ error: result.stderr || "Plan not found" });
         return;
@@ -2516,41 +2203,19 @@ router.get("/plan/:planId", async (req, res) => {
 });
 // PATCH /api/projects/:projectId/pm/plan/:planId
 router.patch("/plan/:planId", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const { title, description } = req.body;
     const args = ["update", routeParam(req, "planId")];
-    if (title?.trim())
-        args.push("--title", title.trim());
-    if (description !== undefined)
-        args.push("--description", description);
-    const result = await runPm({ args, userId: project.ownerUserId, slug: project.slug, jsonOutput: true });
-    if (!result.ok) {
-        res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to update plan" });
-        return;
-    }
-    broadcastProjectEvent(routeParam(req, "projectId"), {
-        type: "item-updated",
-        data: { itemId: routeParam(req, "planId"), userId: req.user.userId },
-    });
-    res.json(result.parsed || {});
+    pushTitleDescArgs(args, req.body);
+    await runPlanMutation(req, res, project, args, "Failed to update plan");
 });
 // DELETE /api/projects/:projectId/pm/plan/:planId
 router.delete("/plan/:planId", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({
-        args: ["delete", routeParam(req, "planId")],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
+    const result = await projectPm(project, ["delete", routeParam(req, "planId")], true);
     if (!result.ok) {
         res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to delete plan" });
         return;
@@ -2563,11 +2228,9 @@ router.delete("/plan/:planId", async (req, res) => {
 });
 // POST /api/projects/:projectId/pm/plan/:planId/steps
 router.post("/plan/:planId/steps", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const { title, description, dependsOn } = req.body;
     if (!title?.trim()) {
         res.status(400).json({ error: "Title is required" });
@@ -2578,145 +2241,55 @@ router.post("/plan/:planId/steps", async (req, res) => {
         args.push("--description", description);
     if (dependsOn)
         args.push("--depends-on", dependsOn);
-    const result = await runPm({ args, userId: project.ownerUserId, slug: project.slug, jsonOutput: true });
-    if (!result.ok) {
-        res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to add step" });
-        return;
-    }
-    broadcastProjectEvent(routeParam(req, "projectId"), {
-        type: "item-updated",
-        data: { itemId: routeParam(req, "planId"), userId: req.user.userId },
-    });
-    res.status(201).json(result.parsed || {});
+    await runPlanMutation(req, res, project, args, "Failed to add step", 201);
 });
 // PATCH /api/projects/:projectId/pm/plan/:planId/steps/:stepRef
 router.patch("/plan/:planId/steps/:stepRef", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const { title, description } = req.body;
     const args = ["plan", "update-step", routeParam(req, "planId"), routeParam(req, "stepRef")];
-    if (title)
-        args.push("--title", title);
-    if (description)
-        args.push("--description", description);
-    const result = await runPm({ args, userId: project.ownerUserId, slug: project.slug, jsonOutput: true });
-    if (!result.ok) {
-        res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to update step" });
-        return;
-    }
-    broadcastProjectEvent(routeParam(req, "projectId"), {
-        type: "item-updated",
-        data: { itemId: routeParam(req, "planId"), userId: req.user.userId },
-    });
-    res.json(result.parsed || {});
+    pushTitleDescArgs(args, req.body);
+    await runPlanMutation(req, res, project, args, "Failed to update step");
 });
 // POST /api/projects/:projectId/pm/plan/:planId/steps/:stepRef/complete
 router.post("/plan/:planId/steps/:stepRef/complete", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({
-        args: ["plan", "complete-step", routeParam(req, "planId"), routeParam(req, "stepRef")],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
-    if (!result.ok) {
-        res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to complete step" });
-        return;
-    }
-    broadcastProjectEvent(routeParam(req, "projectId"), {
-        type: "item-updated",
-        data: { itemId: routeParam(req, "planId"), userId: req.user.userId },
-    });
-    res.json(result.parsed || {});
+    await runPlanMutation(req, res, project, ["plan", "complete-step", routeParam(req, "planId"), routeParam(req, "stepRef")], "Failed to complete step");
 });
 // POST /api/projects/:projectId/pm/plan/:planId/steps/:stepRef/block
 router.post("/plan/:planId/steps/:stepRef/block", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const { reason } = req.body;
     if (!reason?.trim()) {
         res.status(400).json({ error: "Block reason is required" });
         return;
     }
-    const result = await runPm({
-        args: ["plan", "block-step", routeParam(req, "planId"), routeParam(req, "stepRef"), "--step-blocked-reason", reason.trim()],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
-    if (!result.ok) {
-        res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to block step" });
-        return;
-    }
-    broadcastProjectEvent(routeParam(req, "projectId"), {
-        type: "item-updated",
-        data: { itemId: routeParam(req, "planId"), userId: req.user.userId },
-    });
-    res.json(result.parsed || {});
+    await runPlanMutation(req, res, project, ["plan", "block-step", routeParam(req, "planId"), routeParam(req, "stepRef"), "--step-blocked-reason", reason.trim()], "Failed to block step");
 });
 // DELETE /api/projects/:projectId/pm/plan/:planId/steps/:stepRef
 router.delete("/plan/:planId/steps/:stepRef", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
-        return;
-    }
-    const result = await runPm({
-        args: ["plan", "remove-step", routeParam(req, "planId"), routeParam(req, "stepRef")],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
-    if (!result.ok) {
-        res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to remove step" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    broadcastProjectEvent(routeParam(req, "projectId"), {
-        type: "item-updated",
-        data: { itemId: routeParam(req, "planId"), userId: req.user.userId },
-    });
-    res.json(result.parsed || {});
+    await runPlanMutation(req, res, project, ["plan", "remove-step", routeParam(req, "planId"), routeParam(req, "stepRef")], "Failed to remove step");
 });
 // POST /api/projects/:projectId/pm/plan/:planId/approve
 router.post("/plan/:planId/approve", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
-        return;
-    }
-    const result = await runPm({
-        args: ["plan", "approve", routeParam(req, "planId")],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
-    if (!result.ok) {
-        res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to approve plan" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    broadcastProjectEvent(routeParam(req, "projectId"), {
-        type: "item-updated",
-        data: { itemId: routeParam(req, "planId"), userId: req.user.userId },
-    });
-    res.json(result.parsed || {});
+    await runPlanMutation(req, res, project, ["plan", "approve", routeParam(req, "planId")], "Failed to approve plan");
 });
 // POST /api/projects/:projectId/pm/plan/:planId/materialize
 router.post("/plan/:planId/materialize", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const { materializeType, materializeParent, steps } = req.body;
     const args = ["plan", "materialize", routeParam(req, "planId")];
     if (materializeType)
@@ -2725,7 +2298,7 @@ router.post("/plan/:planId/materialize", async (req, res) => {
         args.push("--materialize-parent", materializeParent);
     if (steps)
         args.push("--steps", steps);
-    const result = await runPm({ args, userId: project.ownerUserId, slug: project.slug, jsonOutput: true });
+    const result = await projectPm(project, args, true);
     if (!result.ok) {
         res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to materialize plan" });
         return;
@@ -2738,39 +2311,21 @@ router.post("/plan/:planId/materialize", async (req, res) => {
 });
 // POST /api/projects/:projectId/pm/plan/:planId/steps/:stepRef/reorder
 router.post("/plan/:planId/steps/:stepRef/reorder", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const { reorderTo } = req.body;
     if (reorderTo === undefined || reorderTo === null || reorderTo === "") {
         res.status(400).json({ error: "reorderTo (new order integer) is required" });
         return;
     }
-    const result = await runPm({
-        args: ["plan", "reorder-step", routeParam(req, "planId"), routeParam(req, "stepRef"), String(reorderTo)],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
-    if (!result.ok) {
-        res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to reorder step" });
-        return;
-    }
-    broadcastProjectEvent(routeParam(req, "projectId"), {
-        type: "item-updated",
-        data: { itemId: routeParam(req, "planId"), userId: req.user.userId },
-    });
-    res.json(result.parsed || {});
+    await runPlanMutation(req, res, project, ["plan", "reorder-step", routeParam(req, "planId"), routeParam(req, "stepRef"), String(reorderTo)], "Failed to reorder step");
 });
 // POST /api/projects/:projectId/pm/plan/:planId/link
 router.post("/plan/:planId/link", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const { link, linkKind, linkNote, promoteToItemDep } = req.body;
     if (!link?.trim()) {
         res.status(400).json({ error: "link (item id) is required" });
@@ -2783,24 +2338,13 @@ router.post("/plan/:planId/link", async (req, res) => {
         args.push("--link-note", linkNote);
     if (promoteToItemDep === "true")
         args.push("--promote-to-item-dep");
-    const result = await runPm({ args, userId: project.ownerUserId, slug: project.slug, jsonOutput: true });
-    if (!result.ok) {
-        res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to link plan" });
-        return;
-    }
-    broadcastProjectEvent(routeParam(req, "projectId"), {
-        type: "item-updated",
-        data: { itemId: routeParam(req, "planId"), userId: req.user.userId },
-    });
-    res.status(201).json(result.parsed || {});
+    await runPlanMutation(req, res, project, args, "Failed to link plan", 201);
 });
 // DELETE /api/projects/:projectId/pm/plan/:planId/link
 router.delete("/plan/:planId/link", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const { link, linkKind } = req.body;
     if (!link?.trim()) {
         res.status(400).json({ error: "link (item id) is required" });
@@ -2809,48 +2353,25 @@ router.delete("/plan/:planId/link", async (req, res) => {
     const args = ["plan", "unlink", routeParam(req, "planId"), "--link", link.trim()];
     if (linkKind)
         args.push("--link-kind", linkKind);
-    const result = await runPm({ args, userId: project.ownerUserId, slug: project.slug, jsonOutput: true });
-    if (!result.ok) {
-        res.status(pmErrorStatus(result)).json({ error: result.stderr || "Failed to unlink plan" });
-        return;
-    }
-    broadcastProjectEvent(routeParam(req, "projectId"), {
-        type: "item-updated",
-        data: { itemId: routeParam(req, "planId"), userId: req.user.userId },
-    });
-    res.json(result.parsed || {});
+    await runPlanMutation(req, res, project, args, "Failed to unlink plan");
 });
 // GET /api/projects/:projectId/pm/upgrade
 // Returns a dry-run preview of what upgrade would do (safe, read-only).
 // POST /api/projects/:projectId/pm/upgrade
 // Runs pm upgrade --packages-only (never upgrades the CLI itself via the web UI).
 router.get("/upgrade", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
-    const result = await runPm({
-        args: ["upgrade", "--dry-run", "--packages-only"],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
+    const result = await projectPm(project, ["upgrade", "--dry-run", "--packages-only"], true);
     res.json(result.ok ? (result.parsed || { dryRun: true }) : { error: result.stderr });
 });
 router.post("/upgrade", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     // Only allow package upgrades from the web UI — never self-upgrade the CLI binary.
-    const result = await runPm({
-        args: ["upgrade", "--packages-only"],
-        userId: project.ownerUserId,
-        slug: project.slug,
-        jsonOutput: true,
-    });
+    const result = await projectPm(project, ["upgrade", "--packages-only"], true);
     if (!result.ok) {
         res.status(pmErrorStatus(result)).json({ error: result.stderr || "Upgrade failed" });
         return;
@@ -2882,11 +2403,9 @@ router.patch("/presence/:clientId", async (req, res) => {
 // GET /api/projects/:projectId/pm/events
 router.get("/events", async (req, res) => {
     try {
-        const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-        if (!project) {
-            res.status(404).json({ error: "Project not found" });
+        const project = await requireProject(req, res);
+        if (!project)
             return;
-        }
     }
     catch (err) {
         console.error("SSE project verification failed:", err);
@@ -2935,11 +2454,9 @@ router.get("/events", async (req, res) => {
 // ─── Presence endpoint ───
 // GET /api/projects/:projectId/pm/presence
 router.get("/presence", async (req, res) => {
-    const project = await verifyProject(req.user.userId, routeParam(req, "projectId"));
-    if (!project) {
-        res.status(404).json({ error: "Project not found" });
+    const project = await requireProject(req, res);
+    if (!project)
         return;
-    }
     const users = getProjectPresence(routeParam(req, "projectId"));
     res.json({ users });
 });