@gethmy/mcp 3.2.0 → 3.3.0

package/dist/index.js

@@ -1384,7 +1384,6 @@ var AGENT_MILESTONE_LIVENESS_MS = 30 * 60 * 1000;
 var AGENT_SWEEP_DAEMON_MS = 30 * 60 * 1000;
 var AGENT_SWEEP_INTERACTIVE_MS = 2 * 60 * 60 * 1000;
 var AGENT_SWEEP_PAUSED_MS = 4 * 60 * 60 * 1000;
-var SWEPT_SESSION_WRITE_GRACE_MS = 60 * 60 * 1000;
 var ACTIVE_STATUSES = new Set(["working", "blocked", "waiting"]);
 // ../harmony-shared/dist/cardLinks.js
 var LINK_TYPE_INVERSES = {
@@ -2612,6 +2611,9 @@ ${untrustedDataBlock(planContent.trim(), {
   async updatePlaybook(playbookId, updates) {
     return this.request("PATCH", `/playbooks/${playbookId}`, updates);
   }
+  async deletePlaybook(playbookId) {
+    return this.request("DELETE", `/playbooks/${encodeURIComponent(playbookId)}`);
+  }
 }
 var _promptModules = null;
 async function loadPromptModules() {
@@ -2849,6 +2851,36 @@ async function autoEndSession(scope, client3, cardId, status) {
   } catch {}
 }
 
+// src/comment-session.ts
+var RUN_SESSION_CARD_ENV = "HARMONY_AGENT_CARD_ID";
+var RUN_SESSION_ID_ENV = "HARMONY_AGENT_SESSION_ID";
+function readDeclaredRunSession(env = process.env) {
+  const cardId = env[RUN_SESSION_CARD_ENV]?.trim();
+  const agentSessionId = env[RUN_SESSION_ID_ENV]?.trim();
+  if (!cardId || !agentSessionId)
+    return null;
+  return { cardId, agentSessionId };
+}
+function chooseCommentSession(args) {
+  const tracked = args.tracked;
+  if (tracked?.agentSessionId && tracked.scopeId === args.callerScopeId) {
+    return {
+      kind: "session",
+      agentSessionId: tracked.agentSessionId,
+      source: "tracked"
+    };
+  }
+  const declared = args.declared;
+  if (declared && declared.cardId === args.cardId) {
+    return {
+      kind: "session",
+      agentSessionId: declared.agentSessionId,
+      source: "declared"
+    };
+  }
+  return { kind: "sessionless" };
+}
+
 // src/server.ts
 init_config();
 
@@ -3447,6 +3479,51 @@ async function onboardNewUser(params) {
   };
 }
 
+// src/plan-task-link.ts
+function findPlanTask(tasks, taskId) {
+  if (!taskId) {
+    return { ok: false, reason: "No plan task id was given." };
+  }
+  if (!Array.isArray(tasks)) {
+    return {
+      ok: false,
+      reason: "The plan returned no readable criteria list."
+    };
+  }
+  for (const row of tasks) {
+    if (!row || typeof row !== "object")
+      continue;
+    const candidate = row;
+    if (candidate.id === taskId) {
+      return { ok: true, task: candidate };
+    }
+  }
+  return {
+    ok: false,
+    reason: `Plan task ${taskId} is not one of this plan's criteria. ` + `Read the plan with harmony_get_plan and use an id from its \`tasks\`.`
+  };
+}
+function linkedReport(planId, task, newCardId) {
+  const previous = task.card_id ?? null;
+  return {
+    planId,
+    taskId: task.id,
+    linked: true,
+    criterion: task.content ?? null,
+    ...previous && previous !== newCardId ? { replacedCardId: previous } : {}
+  };
+}
+function unlinkedReport(planId, task, error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    planId,
+    taskId: task.id,
+    linked: false,
+    criterion: task.content ?? null,
+    error: `The card was created, but the plan criterion still does not point at it: ${message}. ` + `Repair it with harmony_link_plan_task — do not create the card again.`
+  };
+}
+
 // src/playbook-metric-warnings.ts
 function playbookMetricWarnings(agents, steps) {
   if (!Array.isArray(steps))
@@ -3944,12 +4021,13 @@ function optionalNonNegativeNumberArg(raw, field) {
     throw new Error(`${field} must be a non-negative number.`);
   return n;
 }
-function initMemorySession(cardId, agentIdentifier, agentName, agentSessionId) {
+function initMemorySession(cardId, agentIdentifier, agentName, agentSessionId, scopeId) {
   memorySessions.set(cardId, {
     cardId,
     agentIdentifier,
     agentName,
     agentSessionId,
+    scopeId,
     memoryReadCount: 0,
     pendingActions: [],
     allActions: [],
@@ -4061,6 +4139,10 @@ var TOOLS = {
           type: "string",
           description: "Plan ID to link this card to (optional). Links the card to that plan via its plan_id."
         },
+        planTaskId: {
+          type: "string",
+          description: "Id of the plan CRITERION this card is created to fulfil (optional; requires `planId`). " + "Sets both directions at once: the card's plan_id, and the criterion's card_id — the " + "return leg a card outcome needs to reach the plan. Read the ids from harmony_get_plan's " + "`tasks`. A criterion that is not in the named plan refuses the whole call, so no card is " + "created on a false premise; a failure to write the return leg AFTER the card exists " + "keeps the card and reports it in `planTask` instead."
+        },
         attachments: {
           type: "array",
           description: "Optional reference files to attach to the new card (e.g. a screenshot from the prompt). " + "Max 5MB each; PNG/JPEG/GIF/WebP/HEIC/HEIF/PDF/DOC(X)/XLS(X)/TXT/CSV. Each file's bytes " + "come from `filePath` (absolute local path the server reads, preferred) or `base64Data` " + "(small-file fallback; requires fileName). NOTE: a pasted image only attaches if your " + "harness has written it to a local file you can pass as filePath — a model cannot re-emit " + "pasted image bytes into base64Data. Per-file failures never block card creation; they are " + "reported back in the result's `attachments` array so you can retry via harmony_upload.",
@@ -5538,6 +5620,29 @@ var TOOLS = {
       required: ["planId"]
     }
   },
+  harmony_link_plan_task: {
+    description: "Point a plan CRITERION at the card that fulfils it, and/or set the criterion's status. " + "A plan task is a success criterion, not a work item: `cards.plan_id` says which plan a card " + "belongs to, and this sets the return leg the plan needs to show real progress instead of " + "guessing from board-column names. Use it to repair a link, to re-point a criterion at a " + "different card, or to mark a criterion `completed` once its card actually delivered it. " + "Leave a criterion the card did NOT deliver open — an open criterion is the signal.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        planId: { type: "string", description: "Plan ID owning the criterion" },
+        taskId: {
+          type: "string",
+          description: "Criterion id, from harmony_get_plan's `tasks`. Must belong to `planId`."
+        },
+        cardId: {
+          type: "string",
+          description: "Card that fulfils this criterion. Must live in the plan's own project."
+        },
+        status: {
+          type: "string",
+          enum: ["pending", "in_progress", "completed"],
+          description: "Criterion status. Set `completed` only when the card demonstrably delivered it."
+        }
+      },
+      required: ["planId", "taskId"]
+    }
+  },
   harmony_list_playbook: {
     description: "List a workspace's playbooks (reusable process definitions). Returns each playbook's name, version, and state. Read-only.",
     inputSchema: {
@@ -5632,6 +5737,19 @@ var TOOLS = {
       required: ["playbookId"]
     }
   },
+  harmony_delete_playbook: {
+    description: "Permanently delete a playbook. IRREVERSIBLE and cascading: its version snapshots and run history are deleted with it, and every card currently running it is unbound — the card stays on the board and keeps its column, but loses its playbook, its pinned version and its stage pointer, so the agent daemon stops treating it as a stage card. Prefer harmony_update_playbook with state='deprecated' unless the playbook should never have existed: a deprecated playbook stays applicable to in-flight cards and is only hidden from new applies. Requires the playbook's creator or a workspace owner/admin — and an ARMED playbook (triggerType 'auto') takes an owner/admin even from its creator, because removing it stops the workspace's automation for everyone. Anyone else is refused and the playbook is left alone. Returns unboundCardCount (the exact number of cards it unbound) and unboundCards (up to 50 of them by id, short_id, title and the stage each one lost).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        playbookId: {
+          type: "string",
+          description: "Playbook ID to delete (UUID)"
+        }
+      },
+      required: ["playbookId"]
+    }
+  },
   harmony_signup: {
     description: "Create a new user account. Returns a JWT session for subsequent authenticated calls. No API key required.",
     inputSchema: {
@@ -5926,28 +6044,58 @@ async function handleToolCall(name, args, deps) {
         fileName: z.string().optional(),
         contentType: z.string().optional()
       })).parse(args.attachments) : [];
+      const planId = args.planId ? z.string().uuid().parse(args.planId) : undefined;
+      const planTaskId = args.planTaskId ? z.string().uuid().parse(args.planTaskId) : undefined;
+      if (planTaskId && !planId) {
+        throw new Error("planTaskId requires planId: no route resolves a plan from a criterion id alone. " + "Pass the plan the criterion belongs to — harmony_get_plan returns both.");
+      }
+      let criterion;
+      if (planTaskId && planId) {
+        const { tasks } = await client3.getPlan(planId);
+        const found = findPlanTask(tasks, planTaskId);
+        if (!found.ok)
+          throw new Error(found.reason);
+        criterion = found.task;
+      }
       const result = await client3.createCard(projectId, {
         title,
         columnId: args.columnId,
         description: args.description,
         priority: args.priority,
         assigneeId: args.assigneeId,
-        planId: args.planId
+        planId
       });
+      const newCardId = result.card?.id;
+      let planTask;
+      if (criterion && planId) {
+        if (!newCardId) {
+          planTask = unlinkedReport(planId, criterion, new Error("no card id was returned to link against"));
+        } else {
+          try {
+            await client3.updatePlanTask(planId, criterion.id, {
+              cardId: newCardId
+            });
+            planTask = linkedReport(planId, criterion, newCardId);
+          } catch (err) {
+            planTask = unlinkedReport(planId, criterion, err);
+          }
+        }
+      }
+      const planTaskField = planTask ? { planTask } : {};
       if (attachments.length === 0) {
-        return { success: true, ...result };
+        return { success: true, ...result, ...planTaskField };
       }
-      const cardId = result.card?.id;
-      if (!cardId) {
+      if (!newCardId) {
         return {
           success: true,
           ...result,
+          ...planTaskField,
           attachmentWarning: "Card created, but attachments were skipped: no card id was returned to upload against."
         };
       }
       const attachmentResults = await Promise.all(attachments.map(async (file) => {
         try {
-          const uploaded = await attachFileToCard(client3, cardId, file);
+          const uploaded = await attachFileToCard(client3, newCardId, file);
           return { ok: true, attachment: uploaded.attachment };
         } catch (err) {
           return {
@@ -5957,7 +6105,12 @@ async function handleToolCall(name, args, deps) {
           };
         }
       }));
-      return { success: true, ...result, attachments: attachmentResults };
+      return {
+        success: true,
+        ...result,
+        ...planTaskField,
+        attachments: attachmentResults
+      };
     }
     case "harmony_update_card": {
       const cardId = z.string().uuid().parse(args.cardId);
@@ -6441,15 +6594,24 @@ ${list}
       const supersedesId = args.supersedesId !== undefined ? z.string().uuid().parse(args.supersedesId) : undefined;
       const confirmsId = args.confirmsId !== undefined ? z.string().uuid().parse(args.confirmsId) : undefined;
       const replyToId = args.replyToId !== undefined ? z.string().uuid().parse(args.replyToId) : undefined;
-      const agentSessionId = getMemorySession(cardId)?.agentSessionId;
+      const sessionChoice = chooseCommentSession({
+        cardId,
+        tracked: getMemorySession(cardId),
+        callerScopeId: deps.getScopeId?.(),
+        declared: readDeclaredRunSession()
+      });
       const result = await client3.addComment(cardId, body, {
         commentType,
         supersedesId,
         confirmsId,
         replyToId,
-        agentSessionId
+        agentSessionId: sessionChoice.kind === "session" ? sessionChoice.agentSessionId : undefined
       });
-      return { success: true, ...result };
+      return {
+        success: true,
+        ...result,
+        sessionAttribution: sessionChoice.kind === "session" ? sessionChoice.source : "none"
+      };
     }
     case "harmony_get_comments": {
       const cardId = z.string().uuid().parse(args.cardId);
@@ -6673,7 +6835,7 @@ ${options}
         scopeId: deps.getScopeId?.()
       });
       const agentSessionId = result.session?.id;
-      initMemorySession(cardId, agentIdentifier, agentName, agentSessionId);
+      initMemorySession(cardId, agentIdentifier, agentName, agentSessionId, deps.getScopeId?.());
       return {
         success: true,
         assignedTo,
@@ -7374,6 +7536,30 @@ ${options}
       const result = await client3.updatePlan(planId, updates);
       return { success: true, plan: result.plan };
     }
+    case "harmony_link_plan_task": {
+      const planId = z.string().uuid().parse(args.planId);
+      const taskId = z.string().uuid().parse(args.taskId);
+      const cardId = args.cardId ? z.string().uuid().parse(args.cardId) : undefined;
+      const status = args.status ? z.enum(["pending", "in_progress", "completed"]).parse(args.status) : undefined;
+      if (!cardId && !status) {
+        throw new Error("Nothing to do: pass cardId, status, or both.");
+      }
+      const { tasks } = await client3.getPlan(planId);
+      const found = findPlanTask(tasks, taskId);
+      if (!found.ok)
+        throw new Error(found.reason);
+      await client3.updatePlanTask(planId, taskId, { cardId, status });
+      return {
+        success: true,
+        planTask: {
+          planId,
+          taskId,
+          criterion: found.task.content ?? null,
+          ...cardId ? linkedReport(planId, found.task, cardId) : { linked: found.task.card_id != null },
+          ...status ? { status } : {}
+        }
+      };
+    }
     case "harmony_advance_plan": {
       const planId = z.string().uuid().parse(args.planId);
       const summary = args.summary;
@@ -7461,6 +7647,16 @@ ${options}
         ...warnings.length > 0 ? { warnings } : {}
       };
     }
+    case "harmony_delete_playbook": {
+      const playbookId = z.string().uuid().parse(args.playbookId);
+      const result = await client3.deletePlaybook(playbookId);
+      return {
+        success: true,
+        playbook: result.playbook,
+        unboundCardCount: result.unboundCardCount,
+        unboundCards: result.unboundCards
+      };
+    }
     case "harmony_save_card_as_playbook":
       return deprecatedRemovedToolResult("harmony_save_card_as_playbook");
     case "harmony_signup": {

package/dist/lib/api-client.js

@@ -836,7 +836,6 @@ var AGENT_MILESTONE_LIVENESS_MS = 30 * 60 * 1000;
 var AGENT_SWEEP_DAEMON_MS = 30 * 60 * 1000;
 var AGENT_SWEEP_INTERACTIVE_MS = 2 * 60 * 60 * 1000;
 var AGENT_SWEEP_PAUSED_MS = 4 * 60 * 60 * 1000;
-var SWEPT_SESSION_WRITE_GRACE_MS = 60 * 60 * 1000;
 var ACTIVE_STATUSES = new Set(["working", "blocked", "waiting"]);
 // ../harmony-shared/dist/cardLinks.js
 var LINK_TYPE_INVERSES = {
@@ -1982,6 +1981,9 @@ ${untrustedDataBlock(planContent.trim(), {
   async updatePlaybook(playbookId, updates) {
     return this.request("PATCH", `/playbooks/${playbookId}`, updates);
   }
+  async deletePlaybook(playbookId) {
+    return this.request("DELETE", `/playbooks/${encodeURIComponent(playbookId)}`);
+  }
 }
 var _promptModules = null;
 async function loadPromptModules() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/mcp",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "MCP server for Harmony, the shared surface for human–agent teams — agents claim cards, report progress, and move work on your board.",
   "publishConfig": {
     "access": "public"

package/src/api-client.ts

@@ -2374,6 +2374,37 @@ export class HarmonyApiClient {
   ): Promise<{ playbook: unknown }> {
     return this.request("PATCH", `/playbooks/${playbookId}`, updates);
   }
+
+  /**
+   * Delete a playbook (card #856). Irreversible: `playbook_versions` and
+   * `playbook_runs` cascade with it, and every bound card is unbound.
+   *
+   * The unbound cards are the point of the return value — the cards that were
+   * running this playbook stay on the board with their stage pointer cleared,
+   * and the caller has no other way to learn which ones those were.
+   * `unboundCardCount` is exact; `unboundCards` is a capped sample of them.
+   *
+   * The route refuses a caller who is neither the playbook's creator nor a
+   * workspace owner/admin with a 403, distinct from the 404 it answers when the
+   * playbook is already gone. `request` throws on both, so a resolved promise
+   * means the row really was removed.
+   */
+  async deletePlaybook(playbookId: string): Promise<{
+    success: boolean;
+    playbook: { id: string; name: string; workspace_id: string };
+    unboundCardCount: number;
+    unboundCards: Array<{
+      id: string;
+      short_id: number | null;
+      title: string;
+      current_stage: string | null;
+    }>;
+  }> {
+    return this.request(
+      "DELETE",
+      `/playbooks/${encodeURIComponent(playbookId)}`,
+    );
+  }
 }
 
 // Shared types for generateCardPrompt to avoid inline assertions

package/src/comment-session.ts

@@ -0,0 +1,149 @@
+/**
+ * Which session an agent comment names — and when it names none (card #1035).
+ *
+ * ## The question this replaces
+ *
+ * `POST /cards/:id/comments` used to answer "which session?" itself when the
+ * caller sent none: it selected the caller's sessions on the card by `card_id`
+ * + `user_id`. That predicate is true of **every concurrent run of the same
+ * account**, so a second run inherited the first one's attribution — measured
+ * on card #1029, where two findings came back carrying a neighbouring `/hmy`
+ * session's id. The server could not do better, because `user_id` is the only
+ * thing it has and the daemon's API key resolves to the same user as its
+ * launcher's own sessions.
+ *
+ * So the answer moved to the only place that can know it: the process making
+ * the call. This module is that decision, kept pure so it is a table test
+ * rather than a behaviour reconstructed from a live run.
+ *
+ * ## Two sources, and why absence is now an ANSWER rather than a guess
+ *
+ * A caller may hold a session two ways, and both are DECLARATIONS rather than
+ * observations:
+ *
+ * - `tracked` — this process called `harmony_start_agent_session` and kept the
+ *   id (`memorySessions`). It is the interactive `/hmy` path.
+ * - `declared` — the daemon put the run's id in this process's environment
+ *   (`harmonyMcpServer` in `@gethmy/harness`, and `motor-driver.ts` for a stage
+ *   run). It is the daemon path, which needs one because
+ *   `harmony_start_agent_session` is DENIED on a daemon run
+ *   (`STAGE_DAEMON_OWNED_TOOLS`) — the daemon owns the lifecycle, so the agent
+ *   has nothing of its own to track.
+ *
+ * Neither is an inference about the ACCOUNT, and that is the whole change.
+ * The old question — "does this user have a session on this card?" — has an
+ * ambiguous negative, because a process that tracks nothing may still belong to
+ * a user with three live runs. The new question — "was a session declared to
+ * THIS process for THIS card?" — has a definite negative: nothing declared
+ * means this caller holds no session it may claim, which is exactly the
+ * sessionless comment #1033 made legal. There is no third "I do not know"
+ * state left for the server to guess at.
+ *
+ * ## The scope check on `tracked` is load-bearing
+ *
+ * `memorySessions` is keyed by card id alone and lives at module scope, so on
+ * the hosted HTTP transport (`remote.ts`, one process serving every user) a
+ * lookup can return a DIFFERENT user's session for the same card. Claiming it
+ * is not merely wrong attribution — harmony-api verifies an explicit
+ * `agentSessionId` against `user_id` and answers 403 — so the tracked source
+ * carries the scope it was recorded under and is used only when that matches
+ * the caller's. A mismatch is treated as "not mine", never as "theirs".
+ *
+ * ## The card check on `declared` is load-bearing too
+ *
+ * A daemon run comments on its own card and, since #1033, on neighbouring ones
+ * — that is how a finding reaches a card the run does not hold. The run's
+ * session belongs to ONE card, so the declaration carries the card id and is
+ * used only on that card. On any other card the same run is genuinely
+ * sessionless, and says so.
+ */
+
+/** A run's own session, as the daemon declared it to this process. */
+export interface DeclaredRunSession {
+  /** `cards.id` — the card the run holds its session on. */
+  cardId: string;
+  /** `card_agent_context.id` — the run's own session row. */
+  agentSessionId: string;
+}
+
+/** The session this process tracks for a card, and the tenant it belongs to. */
+export interface TrackedCommentSession {
+  /** `card_agent_context.id`, captured when this process started the session. */
+  agentSessionId?: string;
+  /**
+   * The tenant the session was recorded under (`ToolDeps.getScopeId`).
+   * `undefined` on stdio, where the process serves exactly one user.
+   */
+  scopeId?: string;
+}
+
+/** What `harmony_add_comment` should send for `agentSessionId`. */
+export type CommentSessionChoice =
+  | {
+      kind: "session";
+      agentSessionId: string;
+      /** Which declaration named it — for the tool result, so the caller can see. */
+      source: "tracked" | "declared";
+    }
+  | { kind: "sessionless" };
+
+/** The two environment keys the daemon declares a run's session through. */
+export const RUN_SESSION_CARD_ENV = "HARMONY_AGENT_CARD_ID";
+export const RUN_SESSION_ID_ENV = "HARMONY_AGENT_SESSION_ID";
+
+/**
+ * The run this MCP process was started for, if the daemon declared one.
+ *
+ * Read per call rather than latched at startup: the value cannot change under a
+ * stdio server (one process per run), and re-reading keeps this a pure function
+ * of its input, which is what lets the tests drive it with a synthetic
+ * environment instead of `process.env`.
+ *
+ * BOTH keys or nothing. A card id with no session is a run that declared
+ * nothing usable, and a session id with no card cannot be bounded to the card
+ * it belongs to — claiming it on every card is the borrowing this replaces.
+ */
+export function readDeclaredRunSession(
+  env: Record<string, string | undefined> = process.env,
+): DeclaredRunSession | null {
+  const cardId = env[RUN_SESSION_CARD_ENV]?.trim();
+  const agentSessionId = env[RUN_SESSION_ID_ENV]?.trim();
+  if (!cardId || !agentSessionId) return null;
+  return { cardId, agentSessionId };
+}
+
+/**
+ * Decide what a new agent comment on `cardId` is attributed to.
+ *
+ * `tracked` wins over `declared` when both name a session for the card. They
+ * cannot disagree in practice — a daemon run may not open a session of its own
+ * — but if one ever did, the session this process opened is the one it can
+ * prove it owns.
+ */
+export function chooseCommentSession(args: {
+  cardId: string;
+  tracked?: TrackedCommentSession | undefined;
+  /** The caller's tenant (`ToolDeps.getScopeId`); `undefined` on stdio. */
+  callerScopeId?: string | undefined;
+  declared?: DeclaredRunSession | null;
+}): CommentSessionChoice {
+  const tracked = args.tracked;
+  if (tracked?.agentSessionId && tracked.scopeId === args.callerScopeId) {
+    return {
+      kind: "session",
+      agentSessionId: tracked.agentSessionId,
+      source: "tracked",
+    };
+  }
+
+  const declared = args.declared;
+  if (declared && declared.cardId === args.cardId) {
+    return {
+      kind: "session",
+      agentSessionId: declared.agentSessionId,
+      source: "declared",
+    };
+  }
+
+  return { kind: "sessionless" };
+}

package/src/plan-task-link.ts

@@ -0,0 +1,128 @@
+/**
+ * Plan criterion ↔ card linking (card #1038, plan "Harmony SDLC — ein Rückgrat").
+ *
+ * A `plan_task` row is a plan's **success criterion**, not a work item. `cards.plan_id`
+ * has always carried the plan → card direction; `plan_tasks.card_id` is the return leg
+ * ("Linked card ID if task has been converted to a card", 20260127100000). It shipped
+ * with the table and no client ever wrote it, so a card outcome had nowhere to land and
+ * plan progress fell back to matching board-column NAMES (`src/lib/planProgress.ts`).
+ *
+ * Everything here is pure and total, because the interesting cases are the ones a live
+ * call cannot cheaply produce: a criterion that belongs to a different plan, a malformed
+ * task list off the wire, and the half-written state where the card exists but the return
+ * leg did not get written.
+ *
+ * WHY NOTHING HERE RESOLVES A PLAN FROM A TASK ID ALONE: there is no
+ * `GET /plan-tasks/:id` route, and adding one to save the caller a field would be a new
+ * server surface for a lookup the caller already has. `planId` is therefore required
+ * alongside `planTaskId`, which also makes the two impossible to contradict — the plan is
+ * named once and used for both the card's `plan_id` and the criterion's scope.
+ */
+
+/** A `plan_tasks` row as it comes back from `GET /plans/:id`. */
+export interface PlanTaskRow {
+  id: string;
+  plan_id?: string | null;
+  card_id?: string | null;
+  content?: string | null;
+  status?: string | null;
+}
+
+export type PlanTaskLookup =
+  | { ok: true; task: PlanTaskRow }
+  | { ok: false; reason: string };
+
+/**
+ * Find `taskId` among a plan's criteria.
+ *
+ * Fails CLOSED on every shape it does not recognise. The caller uses this to decide
+ * whether to create a card at all, so "I could not read the list" must never be reported
+ * as "the criterion is fine" — a card created against a criterion that does not exist is
+ * a card created on a false premise.
+ */
+export function findPlanTask(tasks: unknown, taskId: string): PlanTaskLookup {
+  if (!taskId) {
+    return { ok: false, reason: "No plan task id was given." };
+  }
+  if (!Array.isArray(tasks)) {
+    return {
+      ok: false,
+      reason: "The plan returned no readable criteria list.",
+    };
+  }
+
+  for (const row of tasks) {
+    if (!row || typeof row !== "object") continue;
+    const candidate = row as PlanTaskRow;
+    if (candidate.id === taskId) {
+      return { ok: true, task: candidate };
+    }
+  }
+
+  return {
+    ok: false,
+    reason:
+      `Plan task ${taskId} is not one of this plan's criteria. ` +
+      `Read the plan with harmony_get_plan and use an id from its \`tasks\`.`,
+  };
+}
+
+/** What happened to the return leg after a card was created. */
+export interface PlanTaskLinkReport {
+  planId: string;
+  taskId: string;
+  /** True once `plan_tasks.card_id` points at the new card. */
+  linked: boolean;
+  /** The criterion text, echoed so the caller sees what the card now answers for. */
+  criterion?: string | null;
+  /** Present only when `linked` is false. */
+  error?: string;
+  /** Set when the criterion already pointed at a different card. */
+  replacedCardId?: string | null;
+}
+
+/**
+ * Build the report for a criterion whose return leg was written.
+ *
+ * `replacedCardId` is reported rather than refused: re-pointing a criterion at a new card
+ * is legitimate (the first card was abandoned, or the criterion moved), and a silent
+ * overwrite is the part that would be wrong.
+ */
+export function linkedReport(
+  planId: string,
+  task: PlanTaskRow,
+  newCardId: string,
+): PlanTaskLinkReport {
+  const previous = task.card_id ?? null;
+  return {
+    planId,
+    taskId: task.id,
+    linked: true,
+    criterion: task.content ?? null,
+    ...(previous && previous !== newCardId ? { replacedCardId: previous } : {}),
+  };
+}
+
+/**
+ * Build the report for a return leg that did NOT get written.
+ *
+ * The card is deliberately kept. A card without its return leg is repairable with
+ * `harmony_link_plan_task`; a card thrown away because a second write failed is not.
+ * The message says exactly that, so the caller does not retry the create.
+ */
+export function unlinkedReport(
+  planId: string,
+  task: PlanTaskRow,
+  error: unknown,
+): PlanTaskLinkReport {
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    planId,
+    taskId: task.id,
+    linked: false,
+    criterion: task.content ?? null,
+    error:
+      `The card was created, but the plan criterion still does not point at it: ${message}. ` +
+      `Repair it with harmony_link_plan_task — do not create the card again.`,
+  };
+}