@gethmy/mcp 3.3.0 → 3.4.0

package/src/server.ts

@@ -81,6 +81,11 @@ import {
   unlinkedReport,
 } from "./plan-task-link.js";
 import { collectPlaybookMetricWarnings } from "./playbook-metric-warnings.js";
+import {
+  beginHookTimeline,
+  endHookTimeline,
+  stopAllRunEventForwarders,
+} from "./run-event-forwarder.js";
 import { stripSkillPreamble } from "./skills.js";
 
 // --- Signed-upload handshake (artifacts & card attachments) ---
@@ -2368,7 +2373,10 @@ export const TOOLS = {
       "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.",
+      "Leave a criterion the card did NOT deliver open — an open criterion is the signal. " +
+      "Linking a card that belongs to no plan yet also adopts it into this one (reported as " +
+      "`cardPlanAdopted`), and linking a card that already belongs to a DIFFERENT plan is " +
+      "refused — move it with harmony_update_card first, so the two directions cannot drift.",
     inputSchema: {
       type: "object",
       properties: {
@@ -2381,7 +2389,9 @@ export const TOOLS = {
         cardId: {
           type: "string",
           description:
-            "Card that fulfils this criterion. Must live in the plan's own project.",
+            "Card that fulfils this criterion. Must live in the plan's own project, and " +
+            "must belong to this plan or to no plan yet — a card already in another plan " +
+            "is refused rather than silently re-pointed.",
         },
         status: {
           type: "string",
@@ -4263,6 +4273,16 @@ export async function handleToolCall(
         deps.getScopeId?.(),
       );
 
+      // Publish the session on disk and start draining the `PostToolUse` hook's
+      // spool (#874). This is what gives an MCP session a tool-call timeline
+      // instead of one row per progress checkpoint. It no-ops on a daemon run
+      // and on any failure — see `beginHookTimeline`.
+      beginHookTimeline({
+        cardId,
+        agentSessionId,
+        getClient: () => client,
+      });
+
       return {
         success: true,
         assignedTo,
@@ -4377,6 +4397,11 @@ export async function handleToolCall(
       await flushMemoryActions(client, cardId);
       cleanupMemorySession(cardId);
 
+      // Drain the hook spool and unpublish while the session row still accepts
+      // appends (#874). Ordered before `endAgentSession` for that reason: the
+      // last tool calls of a run are the ones a reader most wants.
+      await endHookTimeline(cardId);
+
       // End the session — tolerate failure (e.g., session already ended or not found).
       // Typed off the client so the `ended`/`reason` discriminator (#769) reaches the
       // tool payload by contract, not by accident of the spread below. Left absent
@@ -5419,7 +5444,11 @@ export async function handleToolCall(
     }
 
     case "harmony_get_plan": {
-      let result: { plan: unknown; tasks: unknown[] } | null = null;
+      let result: {
+        plan: unknown;
+        tasks: unknown[];
+        foreign_criteria?: unknown[];
+      } | null = null;
 
       if (args.planId) {
         const planId = z.string().uuid().parse(args.planId);
@@ -5427,7 +5456,14 @@ export async function handleToolCall(
       } else if (args.cardId) {
         const cardId = z.string().uuid().parse(args.cardId);
         result = await client.getPlanByCardId(cardId);
-        if (!result) {
+        // Three distinct answers, and they must stay distinct. The route
+        // normalises "nothing to report" to `{plan: null, tasks: []}` rather
+        // than a null body, so a truthiness check alone cannot tell the clean
+        // no-plan card from the divergent one.
+        if (
+          !result ||
+          (result.plan == null && !result.foreign_criteria?.length)
+        ) {
           return {
             success: true,
             plan: null,
@@ -5435,6 +5471,27 @@ export async function handleToolCall(
             message: "No plan linked to this card",
           };
         }
+        // The card belongs to no plan, yet some criterion elsewhere names it (#1054).
+        // Reporting that as "no plan linked" is the silence this card was filed for,
+        // one level up from the daemon: a person asking which plan a card serves must
+        // be told the two directions disagree, and which end to repair.
+        // `result.foreign_criteria?.length` is the whole predicate: the route
+        // always answers with an object, so `result.plan == null` is also true
+        // for the ordinary "this card is in no plan" case. Without the second
+        // half, every plan-less card was told plan criteria point at it and
+        // handed a repair instruction for a problem it did not have — the
+        // card's own failure mode inverted.
+        if (result.plan == null && result.foreign_criteria?.length) {
+          return {
+            success: true,
+            plan: null,
+            tasks: [],
+            divergentCriteria: result.foreign_criteria ?? [],
+            message:
+              "This card belongs to no plan, but plan criteria point at it. " +
+              "Repair it with harmony_update_card (planId) or harmony_link_plan_task.",
+          };
+        }
       } else {
         throw new Error("Either planId or cardId must be provided");
       }
@@ -5443,6 +5500,11 @@ export async function handleToolCall(
         success: true,
         plan: result.plan,
         tasks: result.tasks,
+        // Criteria naming this card from a plan it does not belong to — a data error,
+        // reported rather than folded into `tasks` (#1054). Omitted when there are none.
+        ...(result.foreign_criteria?.length
+          ? { divergentCriteria: result.foreign_criteria }
+          : {}),
       };
     }
 
@@ -5490,7 +5552,14 @@ export async function handleToolCall(
       const found = findPlanTask(tasks, taskId);
       if (!found.ok) throw new Error(found.reason);
 
-      await client.updatePlanTask(planId, taskId, { cardId, status });
+      // Linking also maintains the card's own `plan_id` server-side (#1054) — see the
+      // "which direction carries the truth" note in `_shared/plan-task-card-scope.ts`.
+      // A card that belongs to a DIFFERENT plan is refused there, so this call can throw
+      // where it used to succeed and leave the two columns disagreeing.
+      const result = await client.updatePlanTask(planId, taskId, {
+        cardId,
+        status,
+      });
       return {
         success: true,
         planTask: {
@@ -5500,6 +5569,9 @@ export async function handleToolCall(
           ...(cardId
             ? linkedReport(planId, found.task, cardId)
             : { linked: found.task.card_id != null }),
+          ...(cardId && result.cardPlanAdopted
+            ? { cardPlanAdopted: true }
+            : {}),
           ...(status ? { status } : {}),
         },
       };
@@ -5844,6 +5916,14 @@ export class HarmonyMCPServer {
       } catch {
         // Best-effort
       }
+      try {
+        // Drain any tool calls the hook spooled but the timer had not posted,
+        // and remove the on-disk pointers so a later hook cannot route to a
+        // session this process took with it (#874).
+        await stopAllRunEventForwarders();
+      } catch {
+        // Best-effort
+      }
       destroyAutoSession();
       process.exit(exitCode);
     };