@gethmy/mcp 2.14.0 → 2.16.0

package/dist/cli.js

@@ -1793,12 +1793,43 @@ class HarmonyApiClient {
     const query = params.toString() ? `?${params.toString()}` : "";
     return this.request("GET", `/board/${projectId}${query}`);
   }
+  async getFullBoard(projectId, options) {
+    const { pageSize = 200, ...boardOpts } = options ?? {};
+    const cards = [];
+    let offset = 0;
+    let last = null;
+    for (;; ) {
+      const page = await this.getBoard(projectId, {
+        ...boardOpts,
+        limit: pageSize,
+        offset
+      });
+      last = page;
+      const pageCards = page.cards ?? [];
+      cards.push(...pageCards);
+      const hasMore = page.pagination?.hasMore ?? false;
+      if (!hasMore || pageCards.length === 0)
+        break;
+      offset += pageSize;
+    }
+    return {
+      project: last?.project,
+      columns: last?.columns ?? [],
+      cards,
+      labels: last?.labels ?? [],
+      totalCards: last?.pagination?.totalCards ?? cards.length
+    };
+  }
   async createCard(projectId, data) {
     return this.request("POST", "/cards", { projectId, ...data });
   }
   async updateCard(cardId, updates) {
     return this.request("PATCH", `/cards/${cardId}`, updates);
   }
+  async claimCard(cardId, agentId) {
+    const res = await this.request("PATCH", `/cards/${cardId}`, { assignedAgentId: agentId, ifAssignedAgentNull: true });
+    return { claimed: res.claimed !== false };
+  }
   async moveCard(cardId, columnId, position) {
     return this.request("POST", `/cards/${cardId}/move`, {
       columnId,
@@ -2460,7 +2491,7 @@ function initAutoSession(callback, getClient2, getClientInfo, scopeId = DEFAULT_
   scope.clientGetter = getClient2;
   scope.clientInfoGetter = getClientInfo ?? null;
   if (!inactivityTimer) {
-    inactivityTimer = setInterval(checkInactivity, CHECK_INTERVAL_MS);
+    inactivityTimer = setInterval(sweepTick, CHECK_INTERVAL_MS);
   }
 }
 async function trackActivity(cardId, options) {
@@ -2502,7 +2533,8 @@ async function trackActivity(cardId, options) {
     lastActivityAt: now,
     isExplicit: false,
     agentIdentifier,
-    agentName
+    agentName,
+    status: "working"
   });
 }
 function markExplicit(cardId, options) {
@@ -2521,7 +2553,8 @@ function markExplicit(cardId, options) {
       lastActivityAt: Date.now(),
       isExplicit: true,
       agentIdentifier: options?.agentIdentifier ?? "explicit",
-      agentName: options?.agentName ?? "Explicit Agent"
+      agentName: options?.agentName ?? "Explicit Agent",
+      status: "working"
     });
   }
 }
@@ -2567,6 +2600,31 @@ function checkInactivity() {
     }
   }
 }
+function noteSessionStatus(cardId, status, scopeId = DEFAULT_SCOPE) {
+  const session = scopes.get(scopeId)?.sessions.get(cardId);
+  if (session)
+    session.status = status;
+}
+function heartbeatActiveSessions() {
+  for (const scope of scopes.values()) {
+    const client3 = scope.clientGetter?.();
+    if (!client3)
+      continue;
+    for (const session of scope.sessions.values()) {
+      if ((session.status ?? "working") !== "working")
+        continue;
+      client3.updateAgentProgress(session.cardId, {
+        agentIdentifier: session.agentIdentifier,
+        agentName: session.agentName,
+        status: "working"
+      }).catch(() => {});
+    }
+  }
+}
+function sweepTick() {
+  checkInactivity();
+  heartbeatActiveSessions();
+}
 async function autoEndSession(scope, client3, cardId, status) {
   if (!scope.sessions.delete(cardId))
     return;
@@ -6203,10 +6261,14 @@ async function handleToolCall(name, args, deps) {
         mergedRecentActions = callerRecentActions;
       }
       const runActivity = (callerActions || []).map((a) => a.description).filter((d) => typeof d === "string" && d.length > 0);
+      const reportedStatus = args.status;
+      if (reportedStatus) {
+        noteSessionStatus(cardId, reportedStatus, deps.getScopeId?.());
+      }
       const result = await client3.updateAgentProgress(cardId, {
         agentIdentifier,
         agentName,
-        status: args.status,
+        status: reportedStatus,
         progressPercent,
         currentTask: args.currentTask,
         blockers: args.blockers,
@@ -6277,11 +6339,11 @@ async function handleToolCall(name, args, deps) {
     }
     case "harmony_generate_prompt": {
       let cardId;
+      const projectId = args.projectId || deps.getActiveProjectId() || undefined;
       if (args.cardId) {
         cardId = z.string().uuid().parse(args.cardId);
       } else if (args.shortId !== undefined) {
         const shortId = z.number().int().positive().parse(args.shortId);
-        const projectId = args.projectId || deps.getActiveProjectId();
         if (!projectId) {
           throw new Error("Project ID required when using shortId. Use harmony_set_project_context or provide projectId.");
         }
@@ -6290,23 +6352,40 @@ async function handleToolCall(name, args, deps) {
       } else {
         throw new Error("Either cardId or shortId must be provided");
       }
-      let cardTitle = "";
-      let cardDescription = "";
+      const variant = args.variant || undefined;
+      const customConstraints = typeof args.customConstraints === "string" ? args.customConstraints : undefined;
+      const contextOptions = {
+        includeSubtasks: args.includeSubtasks !== false,
+        includeLinks: args.includeLinks !== false,
+        includeDescription: args.includeDescription !== false
+      };
       try {
-        const { card } = await client3.getCard(cardId);
-        const typedCard = card;
-        cardTitle = typedCard.title || "";
-        cardDescription = typedCard.description || "";
-      } catch {}
-      const taskBlock = [cardTitle, cardDescription].filter(Boolean).join(`
+        const result = await client3.generateCardPrompt({
+          cardId,
+          workspaceId: deps.getActiveWorkspaceId() || "",
+          projectId,
+          variant,
+          customConstraints,
+          contextOptions
+        });
+        return { success: true, ...result };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.debug(`[harmony_generate_prompt] falling back: ${msg}`);
+        let cardTitle = "";
+        let cardDescription = "";
+        try {
+          const { card } = await client3.getCard(cardId);
+          const typedCard = card;
+          cardTitle = typedCard.title || "";
+          cardDescription = typedCard.description || "";
+        } catch {}
+        const taskBlock = [cardTitle, cardDescription].filter(Boolean).join(`
 
 `);
-      const prompt = `Here is the task: ${taskBlock || "(no description available)"}`;
-      return {
-        success: true,
-        prompt,
-        cardId
-      };
+        const prompt = `Here is the task: ${taskBlock || "(no description available)"}`;
+        return { success: true, prompt, cardId };
+      }
     }
     case "harmony_remember": {
       const title = z.string().min(1).max(300).parse(args.title);

package/dist/index.js

@@ -1788,12 +1788,43 @@ class HarmonyApiClient {
     const query = params.toString() ? `?${params.toString()}` : "";
     return this.request("GET", `/board/${projectId}${query}`);
   }
+  async getFullBoard(projectId, options) {
+    const { pageSize = 200, ...boardOpts } = options ?? {};
+    const cards = [];
+    let offset = 0;
+    let last = null;
+    for (;; ) {
+      const page = await this.getBoard(projectId, {
+        ...boardOpts,
+        limit: pageSize,
+        offset
+      });
+      last = page;
+      const pageCards = page.cards ?? [];
+      cards.push(...pageCards);
+      const hasMore = page.pagination?.hasMore ?? false;
+      if (!hasMore || pageCards.length === 0)
+        break;
+      offset += pageSize;
+    }
+    return {
+      project: last?.project,
+      columns: last?.columns ?? [],
+      cards,
+      labels: last?.labels ?? [],
+      totalCards: last?.pagination?.totalCards ?? cards.length
+    };
+  }
   async createCard(projectId, data) {
     return this.request("POST", "/cards", { projectId, ...data });
   }
   async updateCard(cardId, updates) {
     return this.request("PATCH", `/cards/${cardId}`, updates);
   }
+  async claimCard(cardId, agentId) {
+    const res = await this.request("PATCH", `/cards/${cardId}`, { assignedAgentId: agentId, ifAssignedAgentNull: true });
+    return { claimed: res.claimed !== false };
+  }
   async moveCard(cardId, columnId, position) {
     return this.request("POST", `/cards/${cardId}/move`, {
       columnId,
@@ -2455,7 +2486,7 @@ function initAutoSession(callback, getClient2, getClientInfo, scopeId = DEFAULT_
   scope.clientGetter = getClient2;
   scope.clientInfoGetter = getClientInfo ?? null;
   if (!inactivityTimer) {
-    inactivityTimer = setInterval(checkInactivity, CHECK_INTERVAL_MS);
+    inactivityTimer = setInterval(sweepTick, CHECK_INTERVAL_MS);
   }
 }
 async function trackActivity(cardId, options) {
@@ -2497,7 +2528,8 @@ async function trackActivity(cardId, options) {
     lastActivityAt: now,
     isExplicit: false,
     agentIdentifier,
-    agentName
+    agentName,
+    status: "working"
   });
 }
 function markExplicit(cardId, options) {
@@ -2516,7 +2548,8 @@ function markExplicit(cardId, options) {
       lastActivityAt: Date.now(),
       isExplicit: true,
       agentIdentifier: options?.agentIdentifier ?? "explicit",
-      agentName: options?.agentName ?? "Explicit Agent"
+      agentName: options?.agentName ?? "Explicit Agent",
+      status: "working"
     });
   }
 }
@@ -2562,6 +2595,31 @@ function checkInactivity() {
     }
   }
 }
+function noteSessionStatus(cardId, status, scopeId = DEFAULT_SCOPE) {
+  const session = scopes.get(scopeId)?.sessions.get(cardId);
+  if (session)
+    session.status = status;
+}
+function heartbeatActiveSessions() {
+  for (const scope of scopes.values()) {
+    const client3 = scope.clientGetter?.();
+    if (!client3)
+      continue;
+    for (const session of scope.sessions.values()) {
+      if ((session.status ?? "working") !== "working")
+        continue;
+      client3.updateAgentProgress(session.cardId, {
+        agentIdentifier: session.agentIdentifier,
+        agentName: session.agentName,
+        status: "working"
+      }).catch(() => {});
+    }
+  }
+}
+function sweepTick() {
+  checkInactivity();
+  heartbeatActiveSessions();
+}
 async function autoEndSession(scope, client3, cardId, status) {
   if (!scope.sessions.delete(cardId))
     return;
@@ -6198,10 +6256,14 @@ async function handleToolCall(name, args, deps) {
         mergedRecentActions = callerRecentActions;
       }
       const runActivity = (callerActions || []).map((a) => a.description).filter((d) => typeof d === "string" && d.length > 0);
+      const reportedStatus = args.status;
+      if (reportedStatus) {
+        noteSessionStatus(cardId, reportedStatus, deps.getScopeId?.());
+      }
       const result = await client3.updateAgentProgress(cardId, {
         agentIdentifier,
         agentName,
-        status: args.status,
+        status: reportedStatus,
         progressPercent,
         currentTask: args.currentTask,
         blockers: args.blockers,
@@ -6272,11 +6334,11 @@ async function handleToolCall(name, args, deps) {
     }
     case "harmony_generate_prompt": {
       let cardId;
+      const projectId = args.projectId || deps.getActiveProjectId() || undefined;
       if (args.cardId) {
         cardId = z.string().uuid().parse(args.cardId);
       } else if (args.shortId !== undefined) {
         const shortId = z.number().int().positive().parse(args.shortId);
-        const projectId = args.projectId || deps.getActiveProjectId();
         if (!projectId) {
           throw new Error("Project ID required when using shortId. Use harmony_set_project_context or provide projectId.");
         }
@@ -6285,23 +6347,40 @@ async function handleToolCall(name, args, deps) {
       } else {
         throw new Error("Either cardId or shortId must be provided");
       }
-      let cardTitle = "";
-      let cardDescription = "";
+      const variant = args.variant || undefined;
+      const customConstraints = typeof args.customConstraints === "string" ? args.customConstraints : undefined;
+      const contextOptions = {
+        includeSubtasks: args.includeSubtasks !== false,
+        includeLinks: args.includeLinks !== false,
+        includeDescription: args.includeDescription !== false
+      };
       try {
-        const { card } = await client3.getCard(cardId);
-        const typedCard = card;
-        cardTitle = typedCard.title || "";
-        cardDescription = typedCard.description || "";
-      } catch {}
-      const taskBlock = [cardTitle, cardDescription].filter(Boolean).join(`
+        const result = await client3.generateCardPrompt({
+          cardId,
+          workspaceId: deps.getActiveWorkspaceId() || "",
+          projectId,
+          variant,
+          customConstraints,
+          contextOptions
+        });
+        return { success: true, ...result };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.debug(`[harmony_generate_prompt] falling back: ${msg}`);
+        let cardTitle = "";
+        let cardDescription = "";
+        try {
+          const { card } = await client3.getCard(cardId);
+          const typedCard = card;
+          cardTitle = typedCard.title || "";
+          cardDescription = typedCard.description || "";
+        } catch {}
+        const taskBlock = [cardTitle, cardDescription].filter(Boolean).join(`
 
 `);
-      const prompt = `Here is the task: ${taskBlock || "(no description available)"}`;
-      return {
-        success: true,
-        prompt,
-        cardId
-      };
+        const prompt = `Here is the task: ${taskBlock || "(no description available)"}`;
+        return { success: true, prompt, cardId };
+      }
     }
     case "harmony_remember": {
       const title = z.string().min(1).max(300).parse(args.title);

package/dist/lib/api-client.js

@@ -1240,12 +1240,43 @@ class HarmonyApiClient {
     const query = params.toString() ? `?${params.toString()}` : "";
     return this.request("GET", `/board/${projectId}${query}`);
   }
+  async getFullBoard(projectId, options) {
+    const { pageSize = 200, ...boardOpts } = options ?? {};
+    const cards = [];
+    let offset = 0;
+    let last = null;
+    for (;; ) {
+      const page = await this.getBoard(projectId, {
+        ...boardOpts,
+        limit: pageSize,
+        offset
+      });
+      last = page;
+      const pageCards = page.cards ?? [];
+      cards.push(...pageCards);
+      const hasMore = page.pagination?.hasMore ?? false;
+      if (!hasMore || pageCards.length === 0)
+        break;
+      offset += pageSize;
+    }
+    return {
+      project: last?.project,
+      columns: last?.columns ?? [],
+      cards,
+      labels: last?.labels ?? [],
+      totalCards: last?.pagination?.totalCards ?? cards.length
+    };
+  }
   async createCard(projectId, data) {
     return this.request("POST", "/cards", { projectId, ...data });
   }
   async updateCard(cardId, updates) {
     return this.request("PATCH", `/cards/${cardId}`, updates);
   }
+  async claimCard(cardId, agentId) {
+    const res = await this.request("PATCH", `/cards/${cardId}`, { assignedAgentId: agentId, ifAssignedAgentNull: true });
+    return { claimed: res.claimed !== false };
+  }
   async moveCard(cardId, columnId, position) {
     return this.request("POST", `/cards/${cardId}/move`, {
       columnId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/mcp",
-  "version": "2.14.0",
+  "version": "2.16.0",
   "description": "MCP server for Harmony Kanban board - enables AI coding agents to manage your boards",
   "publishConfig": {
     "access": "public"
@@ -64,7 +64,7 @@
     "serve:remote": "bun src/remote.ts",
     "dev": "bun --watch src/index.ts",
     "test": "bun run test:unit && bun run test:integration",
-    "test:unit": "bun test src/__tests__/active-learning.test.ts src/__tests__/context-assembly.test.ts src/__tests__/prompt-builder.test.ts src/__tests__/memory-audit.test.ts src/__tests__/skills.test.ts src/__tests__/hmy-config.test.ts src/__tests__/tool-dispatch.test.ts src/__tests__/mcp-integration.test.ts",
+    "test:unit": "bun test src/__tests__/active-learning.test.ts src/__tests__/context-assembly.test.ts src/__tests__/prompt-builder.test.ts src/__tests__/memory-audit.test.ts src/__tests__/skills.test.ts src/__tests__/hmy-config.test.ts src/__tests__/tool-dispatch.test.ts src/__tests__/mcp-integration.test.ts src/__tests__/auto-session.test.ts",
     "test:integration": "bun test src/__tests__/integration-memory-system.test.ts src/__tests__/integration-memory-crud.test.ts",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "bun run typecheck && bun run build"

package/src/api-client.ts

@@ -527,6 +527,70 @@ export class HarmonyApiClient {
     return this.request("GET", `/board/${projectId}${query}`);
   }
 
+  /**
+   * Fetch the FULL board — every non-archived card — by paginating past the
+   * server's default 50-card window (`getBoard` caps at `limit=50` to keep MCP
+   * responses under the token budget).
+   *
+   * Daemon board scans must see the whole board: with the 50-card cap the
+   * entire `Review` column fell outside the first-50-by-position window once a
+   * project crossed 50 cards, silently starving the review pipeline (#628 — a
+   * 272-card project had 0 reviews for ~2 days). This has no LLM-context/token
+   * concern daemon-side, so it walks `offset` until `pagination.hasMore` is
+   * false and concatenates every page's cards.
+   *
+   * Summary mode carries no `cards` array, so callers that only need per-column
+   * counts should keep using `getBoard({ summary: true })`. This is the
+   * card-list path.
+   */
+  async getFullBoard(
+    projectId: string,
+    options?: {
+      columnId?: string;
+      includeArchived?: boolean;
+      labelName?: string;
+      /** Page size for the offset walk. Defaults to 200. */
+      pageSize?: number;
+    },
+  ): Promise<{
+    project: unknown;
+    columns: unknown[];
+    cards: unknown[];
+    labels: unknown[];
+    totalCards: number;
+  }> {
+    const { pageSize = 200, ...boardOpts } = options ?? {};
+    const cards: unknown[] = [];
+    let offset = 0;
+    let last: Awaited<ReturnType<HarmonyApiClient["getBoard"]>> | null = null;
+
+    // Walk pages until the server reports no more. Guard on `hasMore` (not
+    // `cards.length`) so a label-filtered final page shorter than pageSize
+    // terminates cleanly; the empty-page break is a belt-and-braces backstop
+    // against a server that omits `pagination`.
+    for (;;) {
+      const page = await this.getBoard(projectId, {
+        ...boardOpts,
+        limit: pageSize,
+        offset,
+      });
+      last = page;
+      const pageCards = page.cards ?? [];
+      cards.push(...pageCards);
+      const hasMore = page.pagination?.hasMore ?? false;
+      if (!hasMore || pageCards.length === 0) break;
+      offset += pageSize;
+    }
+
+    return {
+      project: last?.project,
+      columns: last?.columns ?? [],
+      cards,
+      labels: last?.labels ?? [],
+      totalCards: last?.pagination?.totalCards ?? cards.length,
+    };
+  }
+
   // ============ CARD OPERATIONS ============
 
   async createCard(
@@ -561,6 +625,25 @@ export class HarmonyApiClient {
     return this.request("PATCH", `/cards/${cardId}`, updates);
   }
 
+  /**
+   * Compare-and-set claim of a card for a virtual agent: sets assigned_agent_id
+   * only if it is currently NULL (server-side guard). Returns `{ claimed: false }`
+   * when another daemon already owns it. Used by the agent-agnostic review pickup.
+   */
+  async claimCard(
+    cardId: string,
+    agentId: string,
+  ): Promise<{ claimed: boolean }> {
+    const res = await this.request<{ card?: unknown; claimed?: boolean }>(
+      "PATCH",
+      `/cards/${cardId}`,
+      { assignedAgentId: agentId, ifAssignedAgentNull: true },
+    );
+    // Success body is `{ card }` (no `claimed` key) → won. Lost-race body is
+    // `{ claimed: false }`.
+    return { claimed: res.claimed !== false };
+  }
+
   async moveCard(
     cardId: string,
     columnId: string,

package/src/auto-session.ts

@@ -25,6 +25,16 @@
 
 import type { HarmonyApiClient } from "./api-client.js";
 
+/**
+ * Status reported for a tracked session. Drives the heartbeat decision: only
+ * `working` sessions are heartbeated by the sweep. `paused`/`blocked`/`waiting`
+ * are intentional non-heartbeat states — the agent has deliberately stopped
+ * making progress (parked for a human, awaiting input, …), so bumping their
+ * `updated_at` would both keep a paused row looking active and mask a genuinely
+ * stalled run.
+ */
+export type SessionStatus = "working" | "blocked" | "waiting" | "paused";
+
 export interface TrackedSession {
   cardId: string;
   startedAt: number;
@@ -33,6 +43,11 @@ export interface TrackedSession {
   isExplicit: boolean;
   agentIdentifier: string;
   agentName: string;
+  /**
+   * Last status reported for the session (default `working`). Only `working`
+   * sessions are heartbeated by the sweep; see `heartbeatActiveSessions`.
+   */
+  status?: SessionStatus;
 }
 
 export type EndSessionCallback = (
@@ -173,7 +188,7 @@ export function initAutoSession(
   // the remote transport, connections arrive faster than the 60s interval and a
   // restart-each-time would keep deferring the sweep indefinitely (starvation).
   if (!inactivityTimer) {
-    inactivityTimer = setInterval(checkInactivity, CHECK_INTERVAL_MS);
+    inactivityTimer = setInterval(sweepTick, CHECK_INTERVAL_MS);
   }
 }
 
@@ -256,6 +271,7 @@ export async function trackActivity(
     isExplicit: false,
     agentIdentifier,
     agentName,
+    status: "working",
   });
 }
 
@@ -283,6 +299,7 @@ export function markExplicit(
       isExplicit: true,
       agentIdentifier: options?.agentIdentifier ?? "explicit",
       agentName: options?.agentName ?? "Explicit Agent",
+      status: "working",
     });
   }
 }
@@ -376,6 +393,79 @@ export function checkInactivity(): void {
   }
 }
 
+/**
+ * Record the latest status reported for a tracked session so the sweep knows
+ * whether to keep heartbeating it. Wired into `harmony_update_agent_progress`
+ * (server.ts): when an agent reports `paused`/`blocked`/`waiting` the heartbeat
+ * stops for that session (those are intentional non-heartbeat states); a later
+ * `working` report resumes it. No-op when the card isn't tracked in the scope.
+ */
+export function noteSessionStatus(
+  cardId: string,
+  status: SessionStatus,
+  scopeId: string = DEFAULT_SCOPE,
+): void {
+  const session = scopes.get(scopeId)?.sessions.get(cardId);
+  if (session) session.status = status;
+}
+
+/**
+ * Heartbeat every tracked `working` session by writing a status-only
+ * `updateAgentProgress`. The backend's `card_agent_context` update trigger
+ * bumps `updated_at` — the field both the kanban card ribbon
+ * (`isAgentContextLive`) and the header "Connected Agents" panel key off to
+ * decide a session is still live.
+ *
+ * WHY (card #608): an interactive MCP client (Claude Code, Cursor, /hmy) opens a
+ * `card_agent_context` row but, unlike the agent daemon's progress-tracker (60s
+ * heartbeat), only writes progress at milestones — often many minutes apart. On
+ * a long run `updated_at` goes stale and the card drops its live indicator
+ * mid-flight. This sweep gives interactive sessions the same ~60s heartbeat.
+ *
+ * Only `working` sessions are heartbeated; `paused`/`blocked`/`waiting` are
+ * intentional non-heartbeat states (see `SessionStatus`). The payload is
+ * status-only (no currentTask/progressPercent) so the heartbeat never clobbers
+ * the real progress the agent last reported — the trigger still bumps
+ * `updated_at`. Covers both auto-started and explicit sessions (both live in
+ * `scope.sessions`).
+ *
+ * No double-heartbeat for the daemon: `packages/harmony-agent` has its own
+ * progress-tracker heartbeat and never routes through mcp-server auto-sessions.
+ */
+export function heartbeatActiveSessions(): void {
+  for (const scope of scopes.values()) {
+    const client = scope.clientGetter?.();
+    if (!client) continue;
+    for (const session of scope.sessions.values()) {
+      // Default-undefined status is treated as `working` (sessions created
+      // before a status was reported).
+      if ((session.status ?? "working") !== "working") continue;
+      client
+        .updateAgentProgress(session.cardId, {
+          agentIdentifier: session.agentIdentifier,
+          agentName: session.agentName,
+          status: "working",
+        })
+        .catch(() => {
+          // Best-effort: a transient failure just defers the bump to the next
+          // sweep. updateAgentProgress is fire-and-forget here.
+        });
+    }
+  }
+}
+
+/**
+ * One tick of the shared 60s sweep: prune idle auto-sessions
+ * (`checkInactivity`) first, then heartbeat the surviving `working` sessions
+ * (`heartbeatActiveSessions`). Order matters — prune before heartbeat so we
+ * never bump a session we're about to end. Exported for tests; in production
+ * the single process-wide timer calls it every CHECK_INTERVAL_MS.
+ */
+export function sweepTick(): void {
+  checkInactivity();
+  heartbeatActiveSessions();
+}
+
 // --- Internal ---
 
 async function autoEndSession(

package/src/server.ts

@@ -22,6 +22,7 @@ import {
   destroyAutoSession,
   initAutoSession,
   markExplicit,
+  noteSessionStatus,
   shutdownAllSessions,
   trackActivity,
   untrack,
@@ -3684,15 +3685,24 @@ async function handleToolCall(
         .map((a) => a.description)
         .filter((d): d is string => typeof d === "string" && d.length > 0);
 
+      const reportedStatus = args.status as
+        | "working"
+        | "blocked"
+        | "waiting"
+        | "paused"
+        | undefined;
+
+      // Keep the auto-session heartbeat in step with the agent's own status
+      // reports: `paused`/`blocked`/`waiting` stop the 60s heartbeat (intentional
+      // non-heartbeat states), a later `working` resumes it (card #608).
+      if (reportedStatus) {
+        noteSessionStatus(cardId, reportedStatus, deps.getScopeId?.());
+      }
+
       const result = await client.updateAgentProgress(cardId, {
         agentIdentifier,
         agentName,
-        status: args.status as
-          | "working"
-          | "blocked"
-          | "waiting"
-          | "paused"
-          | undefined,
+        status: reportedStatus,
         progressPercent,
         currentTask: args.currentTask as string | undefined,
         blockers: args.blockers as string[] | undefined,
@@ -3814,17 +3824,16 @@ async function handleToolCall(
     }
 
     // Prompt generation
-    // TODO Phase 1: rebuild full context assembly per docs/superpowers/plans/2026-05-07-memory-architecture-v2.md §10
     case "harmony_generate_prompt": {
       // Resolve card ID — either directly or via short ID
       let cardId: string;
+      const projectId =
+        (args.projectId as string) || deps.getActiveProjectId() || undefined;
 
       if (args.cardId) {
         cardId = z.string().uuid().parse(args.cardId);
       } else if (args.shortId !== undefined) {
         const shortId = z.number().int().positive().parse(args.shortId);
-        const projectId =
-          (args.projectId as string) || deps.getActiveProjectId();
         if (!projectId) {
           throw new Error(
             "Project ID required when using shortId. Use harmony_set_project_context or provide projectId.",
@@ -3836,29 +3845,58 @@ async function handleToolCall(
         throw new Error("Either cardId or shortId must be provided");
       }
 
-      // Phase 0: minimal placeholder prompt with no context assembly.
-      // Fetch just the card title/description so the agent has the basics.
-      let cardTitle = "";
-      let cardDescription = "";
+      const variant =
+        (args.variant as "analysis" | "draft" | "execute") || undefined;
+      const customConstraints =
+        typeof args.customConstraints === "string"
+          ? args.customConstraints
+          : undefined;
+
+      // Context toggles default ON — a card's reference fields (linked cards,
+      // external URLs, attachments) are hydrated inside generateCardPrompt so
+      // the prompt carries the links the agent needs to fetch related content.
+      const contextOptions = {
+        includeSubtasks: args.includeSubtasks !== false,
+        includeLinks: args.includeLinks !== false,
+        includeDescription: args.includeDescription !== false,
+      };
+
       try {
-        const { card } = await client.getCard(cardId);
-        const typedCard = card as { title?: string; description?: string };
-        cardTitle = typedCard.title || "";
-        cardDescription = typedCard.description || "";
-      } catch {
-        // Card fetch failed; return an empty task description.
-      }
+        const result = await client.generateCardPrompt({
+          cardId,
+          workspaceId: deps.getActiveWorkspaceId() || "",
+          projectId,
+          variant,
+          customConstraints,
+          contextOptions,
+        });
+        return { success: true, ...result };
+      } catch (err) {
+        // Graceful fallback: if full context assembly fails (e.g. an offline
+        // sub-fetch), still return a usable title/description prompt so the
+        // Harmony command never dead-ends. The reference-link hydration is
+        // best-effort inside generateCardPrompt and won't reach here.
+        const msg = err instanceof Error ? err.message : String(err);
+        console.debug(`[harmony_generate_prompt] falling back: ${msg}`);
+
+        let cardTitle = "";
+        let cardDescription = "";
+        try {
+          const { card } = await client.getCard(cardId);
+          const typedCard = card as { title?: string; description?: string };
+          cardTitle = typedCard.title || "";
+          cardDescription = typedCard.description || "";
+        } catch {
+          // Card fetch failed; return an empty task description.
+        }
 
-      const taskBlock = [cardTitle, cardDescription]
-        .filter(Boolean)
-        .join("\n\n");
-      const prompt = `Here is the task: ${taskBlock || "(no description available)"}`;
+        const taskBlock = [cardTitle, cardDescription]
+          .filter(Boolean)
+          .join("\n\n");
+        const prompt = `Here is the task: ${taskBlock || "(no description available)"}`;
 
-      return {
-        success: true,
-        prompt,
-        cardId,
-      };
+        return { success: true, prompt, cardId };
+      }
     }
 
     // Memory / Knowledge Graph operations