@gethmy/mcp 3.1.0 → 3.3.0

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

package/src/server.ts

@@ -28,6 +28,10 @@ import {
   trackActivity,
   untrack,
 } from "./auto-session.js";
+import {
+  chooseCommentSession,
+  readDeclaredRunSession,
+} from "./comment-session.js";
 import {
   describeActiveContext,
   getActiveProjectId,
@@ -69,6 +73,13 @@ import {
 } from "./memory-session.js";
 import { lintTags, normalizeTags } from "./memory-tags.js";
 import { onboardNewUser } from "./onboard.js";
+import {
+  findPlanTask,
+  linkedReport,
+  type PlanTaskLinkReport,
+  type PlanTaskRow,
+  unlinkedReport,
+} from "./plan-task-link.js";
 import { collectPlaybookMetricWarnings } from "./playbook-metric-warnings.js";
 import { stripSkillPreamble } from "./skills.js";
 
@@ -357,6 +368,18 @@ interface MemorySessionState {
   // without a round-trip. May be undefined if the start endpoint did not
   // return an id (older clients) — `scope: 'session'` will then refuse.
   agentSessionId?: string;
+  /**
+   * The tenant this session was recorded under (`ToolDeps.getScopeId`) —
+   * `undefined` on stdio, where one process serves one user.
+   *
+   * `memorySessions` is keyed by card id ALONE and lives at module scope, so on
+   * the hosted transport (`remote.ts`, one process for every user) a lookup can
+   * hand back another user's session for the same card. Anything that CLAIMS
+   * the tracked session must compare this first — see `comment-session.ts`
+   * (#1035), where claiming a stranger's id means a 403 rather than a wrong
+   * name on a comment.
+   */
+  scopeId?: string;
   memoryReadCount: number;
   pendingActions: { action: string; ts: string }[];
   allActions: { action: string; ts: string }[];
@@ -489,12 +512,14 @@ function initMemorySession(
   agentIdentifier: string,
   agentName: string,
   agentSessionId?: string,
+  scopeId?: string,
 ): void {
   memorySessions.set(cardId, {
     cardId,
     agentIdentifier,
     agentName,
     agentSessionId,
+    scopeId,
     memoryReadCount: 0,
     pendingActions: [],
     allActions: [],
@@ -660,6 +685,16 @@ export const TOOLS = {
           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:
@@ -1316,7 +1351,7 @@ export const TOOLS = {
   // Comment operations
   harmony_add_comment: {
     description:
-      "Post a comment on a card as the agent — converse with the human in the open: report progress, ask a question, record a decision, or note a finding, instead of editing the card description. Set supersedesId to correct an earlier comment, confirmsId to reaffirm one. To answer an open question, reply to it with replyToId.",
+      "Post a comment on a card as the agent — converse with the human in the open: report progress, ask a question, record a decision, or note a finding, instead of editing the card description. Works on ANY card you can see, including one you hold no session on, so you can leave a finding on a neighbouring card without claiming it. Set supersedesId to correct an earlier comment, confirmsId to reaffirm one. To answer an open question, reply to it with replyToId.",
     inputSchema: {
       type: "object",
       properties: {
@@ -2326,6 +2361,39 @@ export const TOOLS = {
     },
   },
 
+  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"],
+    },
+  },
+
   // ============ PLAYBOOK TOOLS (Method/Loop layer) ============
 
   harmony_list_playbook: {
@@ -2435,6 +2503,25 @@ export const TOOLS = {
     },
   },
 
+  harmony_delete_playbook: {
+    // The description carries the cascade because that is where the model
+    // reads it (card #856). Deprecating is the reversible verb and is named
+    // first on purpose: it is almost always the right one, and it is already
+    // available through harmony_update_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"],
+    },
+  },
+
   // ============ ONBOARDING TOOLS ============
   harmony_signup: {
     description:
@@ -2819,7 +2906,12 @@ async function resolveColumnByName(
   return col;
 }
 
-async function handleToolCall(
+/**
+ * Exported for tests (card #1038). A pure helper proves its own signature and nothing
+ * about the call site — the two-direction plan link is only real if THIS switch performs
+ * both writes, so the wiring needs a test that drives the tool by name.
+ */
+export async function handleToolCall(
   name: string,
   args: Record<string, unknown>,
   deps: ToolDeps,
@@ -2877,17 +2969,66 @@ async function handleToolCall(
               )
               .parse(args.attachments)
           : [];
+      // Plan criterion ↔ card, both directions in one call (card #1038).
+      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.",
+        );
+      }
+      // Refuse BEFORE the card exists. A criterion that is not in the named plan means the
+      // caller is pointing at the wrong thing, and a card created on that premise is worse
+      // than no card. A failure AFTER the card exists is handled the other way round below.
+      let criterion: PlanTaskRow | undefined;
+      if (planTaskId && planId) {
+        const { tasks } = await client.getPlan(planId);
+        const found = findPlanTask(tasks, planTaskId);
+        if (!found.ok) throw new Error(found.reason);
+        criterion = found.task;
+      }
+
       const result = await client.createCard(projectId, {
         title,
         columnId: args.columnId as string | undefined,
         description: args.description as string | undefined,
         priority: args.priority as string | undefined,
         assigneeId: args.assigneeId as string | undefined,
-        planId: args.planId as string | undefined,
+        planId,
       });
 
+      const newCardId = (result.card as { id?: string } | null)?.id;
+
+      // The return leg. Never throws: the card is the expensive artifact, and a missing
+      // link is repairable with harmony_link_plan_task. Reported, never swallowed.
+      let planTask: PlanTaskLinkReport | undefined;
+      if (criterion && planId) {
+        if (!newCardId) {
+          planTask = unlinkedReport(
+            planId,
+            criterion,
+            new Error("no card id was returned to link against"),
+          );
+        } else {
+          try {
+            await client.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 };
       }
 
       // Attach reference files (e.g. a prompt screenshot) to the freshly
@@ -2895,11 +3036,11 @@ async function handleToolCall(
       // runs only after createCard returns. A bad attachment must never lose
       // the card — per-file failures are captured and reported alongside the
       // successes rather than throwing out the whole create.
-      const cardId = (result.card as { id?: string } | null)?.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.",
         };
@@ -2907,7 +3048,7 @@ async function handleToolCall(
       const attachmentResults = await Promise.all(
         attachments.map(async (file) => {
           try {
-            const uploaded = await attachFileToCard(client, cardId, file);
+            const uploaded = await attachFileToCard(client, newCardId, file);
             return { ok: true as const, attachment: uploaded.attachment };
           } catch (err) {
             return {
@@ -2918,7 +3059,12 @@ async function handleToolCall(
           }
         }),
       );
-      return { success: true, ...result, attachments: attachmentResults };
+      return {
+        success: true,
+        ...result,
+        ...planTaskField,
+        attachments: attachmentResults,
+      };
     }
 
     case "harmony_update_card": {
@@ -3700,13 +3846,54 @@ async function handleToolCall(
         args.replyToId !== undefined
           ? z.string().uuid().parse(args.replyToId)
           : undefined;
+      // Name our OWN session, or say plainly that we hold none (#1035).
+      //
+      // The server no longer infers either way: the `card_id` + `user_id`
+      // fallback in `createComment` is gone, because it was true of every
+      // concurrent run of the same account and a second run inherited the
+      // first one's attribution (measured on card #1029). So this call is now
+      // the whole answer, and `chooseCommentSession` is where it is decided —
+      // read that module for why an absent declaration is an ANSWER here and
+      // was a guess there.
+      //
+      // Two declarations, never an observation: the session THIS process
+      // started (`memorySessions`, the interactive `/hmy` path, checked against
+      // the caller's tenant), and the one the daemon put in this process's
+      // environment for the run it serves (the daemon path, which needs one
+      // because `harmony_start_agent_session` is denied on a daemon run).
+      //
+      // Note the explicit branch on the server accepts any of the caller's own
+      // sessions on the card regardless of `ended_at`. That is deliberate and
+      // it is what replaced #771's swept-session grace window: a run the
+      // silence sweep cut off still names its own id and its last report is
+      // still a run artifact, with no time bound, because naming the session is
+      // knowledge where the window was a guess.
+      const sessionChoice = chooseCommentSession({
+        cardId,
+        tracked: getMemorySession(cardId),
+        callerScopeId: deps.getScopeId?.(),
+        declared: readDeclaredRunSession(),
+      });
       const result = await client.addComment(cardId, body, {
         commentType,
         supersedesId,
         confirmsId,
         replyToId,
+        agentSessionId:
+          sessionChoice.kind === "session"
+            ? sessionChoice.agentSessionId
+            : undefined,
       });
-      return { success: true, ...result };
+      return {
+        success: true,
+        ...result,
+        // Said out loud rather than left to be inferred from the row: a
+        // sessionless comment is a legal shape (#1033) and a degraded one, and
+        // an agent that expected its run to be named should be able to see
+        // that it was not.
+        sessionAttribution:
+          sessionChoice.kind === "session" ? sessionChoice.source : "none",
+      };
     }
 
     case "harmony_get_comments": {
@@ -4066,7 +4253,15 @@ async function handleToolCall(
       // backend session id so working-memory writes (`scope: 'session'`) bind
       // to the same `card_agent_context` row that progress/end calls target.
       const agentSessionId = (result.session as { id?: string } | null)?.id;
-      initMemorySession(cardId, agentIdentifier, agentName, agentSessionId);
+      // The scope is recorded WITH the session, so a later read can tell "mine"
+      // from "the same card, a different user on this hosted process" (#1035).
+      initMemorySession(
+        cardId,
+        agentIdentifier,
+        agentName,
+        agentSessionId,
+        deps.getScopeId?.(),
+      );
 
       return {
         success: true,
@@ -5272,6 +5467,44 @@ async function handleToolCall(
       return { success: true, plan: result.plan };
     }
 
+    case "harmony_link_plan_task": {
+      // The return leg on its own (card #1038): repair a link, re-point a criterion, or
+      // mark one delivered. `harmony_create_card` writes it at birth; this is every other
+      // moment, and it is what a completion path calls to close the loop.
+      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.");
+      }
+
+      // Same fail-closed read as the create path — the criterion has to be in THIS plan.
+      // The route scopes its update by plan_id too, but a rejection that names the
+      // mistake beats a zero-row update surfacing as an opaque database error.
+      const { tasks } = await client.getPlan(planId);
+      const found = findPlanTask(tasks, taskId);
+      if (!found.ok) throw new Error(found.reason);
+
+      await client.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": {
       // Simplified: just archive the plan
       const planId = z.string().uuid().parse(args.planId);
@@ -5410,6 +5643,26 @@ async function handleToolCall(
       };
     }
 
+    case "harmony_delete_playbook": {
+      const playbookId = z.string().uuid().parse(args.playbookId);
+      // No `confirm` argument, deliberately. Every other destructive tool here
+      // (harmony_delete_card, harmony_delete_column — which deletes its cards)
+      // takes none, and a flag the caller chooses is not a bound: the model
+      // that decided to delete also supplies the confirmation. What actually
+      // holds is the route's creator-or-admin check, the description above
+      // pointing at deprecate, and this reply naming what was unbound.
+      const result = await client.deletePlaybook(playbookId);
+      // The count is the server's exact one; the list is its capped sample. Do
+      // not derive the count from the list — that silently under-reports the
+      // blast radius on exactly the playbook where it matters most.
+      return {
+        success: true,
+        playbook: result.playbook,
+        unboundCardCount: result.unboundCardCount,
+        unboundCards: result.unboundCards,
+      };
+    }
+
     // Deprecated (#612) — see harmony_run_playbook above.
     case "harmony_save_card_as_playbook":
       return deprecatedRemovedToolResult("harmony_save_card_as_playbook");