@gethmy/mcp 2.17.0 → 2.17.1

package/dist/cli.js

@@ -1499,6 +1499,21 @@ var TIMINGS = {
   QUERY_STALE_TIME: 1000 * 60 * 5,
   QUERY_GC_TIME: 1000 * 60 * 60 * 24
 };
+// ../harmony-shared/dist/playbookStage.js
+var STAGE_DAEMON_OWNED_TOOLS = [
+  "mcp__harmony__harmony_end_agent_session",
+  "mcp__harmony__harmony_start_agent_session",
+  "mcp__harmony__harmony_move_card"
+];
+// ../harmony-shared/dist/reviewTools.js
+var REVIEW_DISALLOWED_TOOLS = [
+  ...STAGE_DAEMON_OWNED_TOOLS,
+  "mcp__harmony__harmony_update_card",
+  "mcp__harmony__harmony_create_subtask",
+  "mcp__harmony__harmony_update_subtask",
+  "mcp__harmony__harmony_delete_subtask",
+  "mcp__harmony__harmony_toggle_subtask"
+];
 // ../harmony-shared/dist/stageHandoff.js
 var HANDOFF_MARKER = "harmony:stage-handoff";
 var HANDOFF_BLOCK_RE = new RegExp("```json\\s*\\n//\\s*" + HANDOFF_MARKER + "\\s*\\n([\\s\\S]*?)\\n```", "m");
@@ -1761,6 +1776,9 @@ class HarmonyApiClient {
   async getWorkspaceMembers(workspaceId) {
     return this.request("GET", `/workspaces/${workspaceId}/members`);
   }
+  async getAuthContext() {
+    return this.request("GET", "/auth/context");
+  }
   async listWorkspaceAgents(workspaceId) {
     return this.request("GET", `/workspaces/${workspaceId}/agents`);
   }
@@ -2481,6 +2499,7 @@ var AUTO_START_TRIGGERS = new Set([
 ]);
 var INACTIVITY_TIMEOUT_MS = 10 * 60 * 1000;
 var CHECK_INTERVAL_MS = 60 * 1000;
+var HEARTBEAT_ACTIVITY_WINDOW_MS = 25 * 60 * 1000;
 var DEFAULT_SCOPE = "__default__";
 var scopes = new Map;
 var inactivityTimer = null;
@@ -2618,17 +2637,25 @@ function noteSessionStatus(cardId, status, scopeId = DEFAULT_SCOPE) {
     session.status = status;
 }
 function heartbeatActiveSessions() {
+  const now = Date.now();
   for (const scope of scopes.values()) {
     const client3 = scope.clientGetter?.();
     if (!client3)
       continue;
-    for (const session of scope.sessions.values()) {
+    for (const [cardId, session] of [...scope.sessions.entries()]) {
       if ((session.status ?? "working") !== "working")
         continue;
+      if (now - session.lastActivityAt > HEARTBEAT_ACTIVITY_WINDOW_MS)
+        continue;
       client3.updateAgentProgress(session.cardId, {
         agentIdentifier: session.agentIdentifier,
         agentName: session.agentName,
-        status: "working"
+        status: "working",
+        noCreate: true
+      }).then((res) => {
+        if (res?.session === null && scope.sessions.get(cardId) === session) {
+          scope.sessions.delete(cardId);
+        }
       }).catch(() => {});
     }
   }
@@ -6148,6 +6175,23 @@ async function handleToolCall(name, args, deps) {
     }
     case "harmony_set_workspace_context": {
       const workspaceId = z.string().uuid().parse(args.workspaceId);
+      const { workspaces } = await client3.listWorkspaces();
+      const available = workspaces ?? [];
+      const match = available.find((w) => w?.id === workspaceId);
+      if (!match) {
+        const options = available.filter((w) => w?.id).map((w) => `  - ${w.name ?? "(unnamed)"} (${w.id})`).join(`
+`);
+        throw new Error(`Workspace ${workspaceId} is not available to this connection.
+
+` + `This MCP connection is authorized for a specific workspace, chosen ` + `during OAuth consent — it cannot read or write any other workspace, ` + `even ones you're a member of.
+
+` + (options ? `Available here:
+${options}
+
+` : `No workspaces are available to this connection.
+
+`) + `To work in a different workspace, run /mcp to reconnect and select ` + `it on the consent screen.`);
+      }
       deps.setActiveWorkspace(workspaceId);
       return { success: true, activeWorkspaceId: workspaceId };
     }

package/dist/index.js

@@ -1494,6 +1494,21 @@ var TIMINGS = {
   QUERY_STALE_TIME: 1000 * 60 * 5,
   QUERY_GC_TIME: 1000 * 60 * 60 * 24
 };
+// ../harmony-shared/dist/playbookStage.js
+var STAGE_DAEMON_OWNED_TOOLS = [
+  "mcp__harmony__harmony_end_agent_session",
+  "mcp__harmony__harmony_start_agent_session",
+  "mcp__harmony__harmony_move_card"
+];
+// ../harmony-shared/dist/reviewTools.js
+var REVIEW_DISALLOWED_TOOLS = [
+  ...STAGE_DAEMON_OWNED_TOOLS,
+  "mcp__harmony__harmony_update_card",
+  "mcp__harmony__harmony_create_subtask",
+  "mcp__harmony__harmony_update_subtask",
+  "mcp__harmony__harmony_delete_subtask",
+  "mcp__harmony__harmony_toggle_subtask"
+];
 // ../harmony-shared/dist/stageHandoff.js
 var HANDOFF_MARKER = "harmony:stage-handoff";
 var HANDOFF_BLOCK_RE = new RegExp("```json\\s*\\n//\\s*" + HANDOFF_MARKER + "\\s*\\n([\\s\\S]*?)\\n```", "m");
@@ -1756,6 +1771,9 @@ class HarmonyApiClient {
   async getWorkspaceMembers(workspaceId) {
     return this.request("GET", `/workspaces/${workspaceId}/members`);
   }
+  async getAuthContext() {
+    return this.request("GET", "/auth/context");
+  }
   async listWorkspaceAgents(workspaceId) {
     return this.request("GET", `/workspaces/${workspaceId}/agents`);
   }
@@ -2476,6 +2494,7 @@ var AUTO_START_TRIGGERS = new Set([
 ]);
 var INACTIVITY_TIMEOUT_MS = 10 * 60 * 1000;
 var CHECK_INTERVAL_MS = 60 * 1000;
+var HEARTBEAT_ACTIVITY_WINDOW_MS = 25 * 60 * 1000;
 var DEFAULT_SCOPE = "__default__";
 var scopes = new Map;
 var inactivityTimer = null;
@@ -2613,17 +2632,25 @@ function noteSessionStatus(cardId, status, scopeId = DEFAULT_SCOPE) {
     session.status = status;
 }
 function heartbeatActiveSessions() {
+  const now = Date.now();
   for (const scope of scopes.values()) {
     const client3 = scope.clientGetter?.();
     if (!client3)
       continue;
-    for (const session of scope.sessions.values()) {
+    for (const [cardId, session] of [...scope.sessions.entries()]) {
       if ((session.status ?? "working") !== "working")
         continue;
+      if (now - session.lastActivityAt > HEARTBEAT_ACTIVITY_WINDOW_MS)
+        continue;
       client3.updateAgentProgress(session.cardId, {
         agentIdentifier: session.agentIdentifier,
         agentName: session.agentName,
-        status: "working"
+        status: "working",
+        noCreate: true
+      }).then((res) => {
+        if (res?.session === null && scope.sessions.get(cardId) === session) {
+          scope.sessions.delete(cardId);
+        }
       }).catch(() => {});
     }
   }
@@ -6143,6 +6170,23 @@ async function handleToolCall(name, args, deps) {
     }
     case "harmony_set_workspace_context": {
       const workspaceId = z.string().uuid().parse(args.workspaceId);
+      const { workspaces } = await client3.listWorkspaces();
+      const available = workspaces ?? [];
+      const match = available.find((w) => w?.id === workspaceId);
+      if (!match) {
+        const options = available.filter((w) => w?.id).map((w) => `  - ${w.name ?? "(unnamed)"} (${w.id})`).join(`
+`);
+        throw new Error(`Workspace ${workspaceId} is not available to this connection.
+
+` + `This MCP connection is authorized for a specific workspace, chosen ` + `during OAuth consent — it cannot read or write any other workspace, ` + `even ones you're a member of.
+
+` + (options ? `Available here:
+${options}
+
+` : `No workspaces are available to this connection.
+
+`) + `To work in a different workspace, run /mcp to reconnect and select ` + `it on the consent screen.`);
+      }
       deps.setActiveWorkspace(workspaceId);
       return { success: true, activeWorkspaceId: workspaceId };
     }

package/dist/lib/api-client.js

@@ -946,6 +946,21 @@ var TIMINGS = {
   QUERY_STALE_TIME: 1000 * 60 * 5,
   QUERY_GC_TIME: 1000 * 60 * 60 * 24
 };
+// ../harmony-shared/dist/playbookStage.js
+var STAGE_DAEMON_OWNED_TOOLS = [
+  "mcp__harmony__harmony_end_agent_session",
+  "mcp__harmony__harmony_start_agent_session",
+  "mcp__harmony__harmony_move_card"
+];
+// ../harmony-shared/dist/reviewTools.js
+var REVIEW_DISALLOWED_TOOLS = [
+  ...STAGE_DAEMON_OWNED_TOOLS,
+  "mcp__harmony__harmony_update_card",
+  "mcp__harmony__harmony_create_subtask",
+  "mcp__harmony__harmony_update_subtask",
+  "mcp__harmony__harmony_delete_subtask",
+  "mcp__harmony__harmony_toggle_subtask"
+];
 // ../harmony-shared/dist/stageHandoff.js
 var HANDOFF_MARKER = "harmony:stage-handoff";
 var HANDOFF_BLOCK_RE = new RegExp("```json\\s*\\n//\\s*" + HANDOFF_MARKER + "\\s*\\n([\\s\\S]*?)\\n```", "m");
@@ -1208,6 +1223,9 @@ class HarmonyApiClient {
   async getWorkspaceMembers(workspaceId) {
     return this.request("GET", `/workspaces/${workspaceId}/members`);
   }
+  async getAuthContext() {
+    return this.request("GET", "/auth/context");
+  }
   async listWorkspaceAgents(workspaceId) {
     return this.request("GET", `/workspaces/${workspaceId}/agents`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/mcp",
-  "version": "2.17.0",
+  "version": "2.17.1",
   "description": "MCP server for Harmony Kanban board - enables AI coding agents to manage your boards",
   "publishConfig": {
     "access": "public"

package/src/api-client.ts

@@ -461,6 +461,22 @@ export class HarmonyApiClient {
     return this.request("GET", `/workspaces/${workspaceId}/members`);
   }
 
+  /**
+   * The auth user THIS client's credential resolves to server-side — the id
+   * harmony-api stamps onto sessions it creates for this caller. The agent
+   * daemon uses it to assert its configured `userEmail` and its API key are the
+   * same user; a divergence would make it fail closed on its own comment
+   * artifacts (card #693). `GET /v1/auth/context` is long-deployed (the MCP
+   * transport authenticates every request through it).
+   */
+  async getAuthContext(): Promise<{
+    userId: string;
+    source: "api_key" | "oauth" | "jwt";
+    workspaceId: string | null;
+  }> {
+    return this.request("GET", "/auth/context");
+  }
+
   async listWorkspaceAgents(
     workspaceId: string,
   ): Promise<{ agents: WorkspaceAgent[] }> {
@@ -1067,6 +1083,12 @@ export class HarmonyApiClient {
       recoveryBranch?: string;
       attemptNumber?: number;
       maxAttempts?: number;
+      /**
+       * Update-only: never create a session if none is live, answer
+       * `{session: null}` instead. Set by the auto-session heartbeat, which must
+       * report on a session but must never bring one back from the dead (#696).
+       */
+      noCreate?: boolean;
     },
   ): Promise<{ session: unknown; created: boolean }> {
     return this.request("POST", `/cards/${cardId}/agent-context`, data);
@@ -1075,7 +1097,13 @@ export class HarmonyApiClient {
   async endAgentSession(
     cardId: string,
     data?: {
-      status?: "completed" | "paused" | "failed";
+      /**
+       * `cancelled` marks a HUMAN stop specifically — it is what arms the
+       * server's human-stop cooldown (card #663). Never use it for a graceful
+       * shutdown or an internal abort, which must stay `paused`/`failed` so the
+       * card can be re-picked immediately (card #696).
+       */
+      status?: "completed" | "paused" | "failed" | "cancelled";
       progressPercent?: number;
       costCents?: number;
       inputTokens?: number;

package/src/auto-session.ts

@@ -116,6 +116,27 @@ export const AUTO_START_TRIGGERS = new Set([
 export const INACTIVITY_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes
 const CHECK_INTERVAL_MS = 60 * 1000; // 60 seconds
 
+/**
+ * How long after the agent's last harmony tool call we keep heartbeating a
+ * session (card #696).
+ *
+ * WHY: the heartbeat asserts "this agent is still working". An *explicit*
+ * session (`/hmy`) is exempt from `checkInactivity`, so an unbounded heartbeat
+ * asserted that forever — bumping `updated_at` every 60s and starving the
+ * 30-minute `cleanup_stale_agent_sessions` cron, which is the only backstop for
+ * a session whose agent finished (card moved to Review) but never called
+ * `harmony_end_agent_session`. The session then showed "working" forever.
+ *
+ * Bounding the heartbeat by real activity restores that backstop: once the
+ * agent stops calling harmony tools we stop beating, `updated_at` goes stale,
+ * and the cron closes the row as `failed`/`stale`. Sits deliberately BELOW the
+ * cron's 30-minute threshold so a stalled session can actually reach it, and
+ * well above the milestone-gap the heartbeat exists to bridge (#608). Activity
+ * revives it — `trackActivity` refreshes `lastActivityAt` on every card-scoped
+ * tool call.
+ */
+export const HEARTBEAT_ACTIVITY_WINDOW_MS = 25 * 60 * 1000; // 25 minutes
+
 /**
  * Scope used when no `scopeId` is supplied. stdio is single-user, so it shares
  * one scope; the unit tests also exercise this default scope exclusively.
@@ -429,22 +450,54 @@ export function noteSessionStatus(
  * `updated_at`. Covers both auto-started and explicit sessions (both live in
  * `scope.sessions`).
  *
+ * Two bounds keep a heartbeat from outliving the work it reports on (card #696):
+ *
+ * 1. `noCreate` — a heartbeat may only ever UPDATE a live session, never create
+ *    one. The endpoint shares a single upsert with `start_agent_session`, so
+ *    without this a heartbeat for a session ended out-of-band (the UI "Stop",
+ *    which cannot reach this process's map) re-created the row and re-added the
+ *    `agent` label. The #663 human-stop cooldown only deferred that by 10
+ *    minutes, so a stopped card reliably respawned exactly one cooldown later.
+ *    `session: null` back means the session is gone → untrack, stop beating.
+ * 2. `HEARTBEAT_ACTIVITY_WINDOW_MS` — only beat while the agent is still calling
+ *    harmony tools, so an abandoned session goes stale and the cron can close it.
+ *
  * 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 {
+  const now = Date.now();
   for (const scope of scopes.values()) {
     const client = scope.clientGetter?.();
     if (!client) continue;
-    for (const session of scope.sessions.values()) {
+    // Snapshot: the untrack-on-ended path below mutates the map.
+    for (const [cardId, session] of [...scope.sessions.entries()]) {
       // Default-undefined status is treated as `working` (sessions created
       // before a status was reported).
       if ((session.status ?? "working") !== "working") continue;
+      // Silent agent → stop asserting it's working; hand the row to the cron.
+      if (now - session.lastActivityAt > HEARTBEAT_ACTIVITY_WINDOW_MS) continue;
       client
         .updateAgentProgress(session.cardId, {
           agentIdentifier: session.agentIdentifier,
           agentName: session.agentName,
           status: "working",
+          noCreate: true,
+        })
+        .then((res) => {
+          // Ended out-of-band (UI "Stop", another client, the stale cron). Drop
+          // it so we never beat — nor respawn — this session again. Only an
+          // explicit null counts: an unknown/absent field must not untrack a
+          // live session.
+          //
+          // Identity-checked: this reply describes the session we beat, which
+          // may no longer be the one tracked for this card. An end + restart
+          // landing inside the request's round-trip replaces the map entry, and
+          // deleting by cardId alone would drop that NEW live session — leaving
+          // it unbeaten until the stale cron closed it early.
+          if (res?.session === null && scope.sessions.get(cardId) === session) {
+            scope.sessions.delete(cardId);
+          }
         })
         .catch(() => {
           // Best-effort: a transient failure just defers the bump to the next

package/src/server.ts

@@ -3489,6 +3489,42 @@ async function handleToolCall(
 
     case "harmony_set_workspace_context": {
       const workspaceId = z.string().uuid().parse(args.workspaceId);
+
+      // Fail fast on a workspace this connection can't actually reach (#695).
+      // An OAuth token is bound at consent time to the single workspace the user
+      // picked ("It will be able to read and modify cards, plans, and memory in
+      // the workspace you select below"), and harmony-api enforces that on every
+      // call. Setting the context is a pure local assignment, so without this
+      // check it always "succeeded" and the caller only discovered the binding
+      // when some later, unrelated tool call 403'd mid-task — the exact confusion
+      // this card reports. `listWorkspaces` is server-side scoped to the bound
+      // workspace, so presence in it is the authoritative reachability answer for
+      // OAuth and legacy-key connections alike.
+      const { workspaces } = await client.listWorkspaces();
+      const available = (workspaces ?? []) as Array<{
+        id?: string;
+        name?: string;
+      }>;
+      const match = available.find((w) => w?.id === workspaceId);
+
+      if (!match) {
+        const options = available
+          .filter((w) => w?.id)
+          .map((w) => `  - ${w.name ?? "(unnamed)"} (${w.id})`)
+          .join("\n");
+        throw new Error(
+          `Workspace ${workspaceId} is not available to this connection.\n\n` +
+            `This MCP connection is authorized for a specific workspace, chosen ` +
+            `during OAuth consent — it cannot read or write any other workspace, ` +
+            `even ones you're a member of.\n\n` +
+            (options
+              ? `Available here:\n${options}\n\n`
+              : `No workspaces are available to this connection.\n\n`) +
+            `To work in a different workspace, run /mcp to reconnect and select ` +
+            `it on the consent screen.`,
+        );
+      }
+
       deps.setActiveWorkspace(workspaceId);
       return { success: true, activeWorkspaceId: workspaceId };
     }