@gethmy/mcp 2.16.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`);
   }
@@ -2032,6 +2050,8 @@ class HarmonyApiClient {
       params.set("offset", String(options.offset));
     if (options.include_superseded)
       params.set("include_superseded", "true");
+    if (options.include_episodes)
+      params.set("include_episodes", "true");
     return this.request("GET", `/memory/entities?${params.toString()}`);
   }
   async getMemoryEntity(entityId) {
@@ -2047,7 +2067,8 @@ class HarmonyApiClient {
       const search = await this.searchMemoryEntities(options.workspaceId, options.query, {
         project_id: options.projectId,
         type: options.type?.length === 1 ? options.type[0] : undefined,
-        limit: fetchLimit
+        limit: fetchLimit,
+        include_episodes: options.includeEpisodes
       });
       entities = search.entities ?? [];
     } else {
@@ -2058,7 +2079,8 @@ class HarmonyApiClient {
         type: options.type?.length === 1 ? options.type[0] : undefined,
         tags: options.tags,
         min_confidence: options.minConfidence,
-        limit: fetchLimit
+        limit: fetchLimit,
+        include_episodes: options.includeEpisodes
       });
       entities = list.entities ?? [];
     }
@@ -2119,6 +2141,8 @@ class HarmonyApiClient {
       params.append("tags", tag);
     if (options?.include_superseded)
       params.set("include_superseded", "true");
+    if (options?.include_episodes)
+      params.set("include_episodes", "true");
     return this.request("GET", `/memory/search?${params.toString()}`);
   }
   async getVaultIndex(options) {
@@ -2130,6 +2154,8 @@ class HarmonyApiClient {
       params.set("type", options.type);
     if (options.limit !== undefined)
       params.set("limit", String(options.limit));
+    if (options.include_episodes)
+      params.set("include_episodes", "true");
     return this.request("GET", `/memory/index?${params.toString()}`);
   }
   async getVaultIndexMarkdown(options) {
@@ -2141,6 +2167,8 @@ class HarmonyApiClient {
       params.set("type", options.type);
     if (options.limit !== undefined)
       params.set("limit", String(options.limit));
+    if (options.include_episodes)
+      params.set("include_episodes", "true");
     return this.requestRaw("GET", `/memory/index?${params.toString()}`, undefined, {
       accept: "text/markdown"
     });
@@ -2198,6 +2226,8 @@ class HarmonyApiClient {
       params.set("type", options.type);
     if (options?.limit !== undefined)
       params.set("limit", String(options.limit));
+    if (options?.include_episodes)
+      params.set("include_episodes", "true");
     return this.requestRaw("GET", `/memory/search?${params.toString()}`, undefined, {
       accept: "text/markdown"
     });
@@ -2469,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;
@@ -2606,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(() => {});
     }
   }
@@ -4833,6 +4872,10 @@ var TOOLS = {
         include_superseded: {
           type: "boolean",
           description: "Include rows whose `superseded_at` is set (default false). Use when investigating supersede chains."
+        },
+        include_episodes: {
+          type: "boolean",
+          description: "Include agent-run episodes — the daemon's per-run implement/review captures (default false). Excluded by default so recall surfaces curated, durable memory. Set true to audit the agent's run history."
         }
       }
     }
@@ -5018,7 +5061,11 @@ var TOOLS = {
           type: "string",
           description: "Project ID (optional)"
         },
-        limit: { type: "number", description: "Max results (default: 20)" }
+        limit: { type: "number", description: "Max results (default: 20)" },
+        include_episodes: {
+          type: "boolean",
+          description: "Include agent-run episodes — the daemon's per-run captures (default false). Excluded by default so search surfaces curated memory."
+        }
       },
       required: ["query"]
     }
@@ -5059,6 +5106,10 @@ var TOOLS = {
         limit: {
           type: "number",
           description: "Max entities to return (default: 200)"
+        },
+        include_episodes: {
+          type: "boolean",
+          description: "Include agent-run episodes — the daemon's per-run captures (default false). Excluded by default so the index shows curated vault content, not run noise."
         }
       },
       required: []
@@ -6124,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 };
     }
@@ -6486,6 +6554,7 @@ async function handleToolCall(name, args, deps) {
       const topK = args.top_k;
       const budgetTokens = args.budget_tokens;
       const includeSuperseded = Boolean(args.include_superseded);
+      const includeEpisodes = Boolean(args.include_episodes);
       const queryText = args.query;
       const fetchLimit = Math.min(Math.max(requestedLimit ?? 20, topK ?? 0, 50), 200);
       const projectId = args.projectId || deps.getActiveProjectId() || undefined;
@@ -6502,7 +6571,8 @@ async function handleToolCall(name, args, deps) {
           type: args.type,
           limit: fetchLimit,
           tags: requestedTags && requestedTags.length > 0 ? requestedTags : undefined,
-          include_superseded: includeSuperseded
+          include_superseded: includeSuperseded,
+          include_episodes: includeEpisodes
         });
         entities = searchResult.entities ?? [];
         const minConfidence = args.minConfidence;
@@ -6525,7 +6595,8 @@ async function handleToolCall(name, args, deps) {
           tags: args.tags,
           min_confidence: args.minConfidence,
           limit: fetchLimit,
-          include_superseded: includeSuperseded
+          include_superseded: includeSuperseded,
+          include_episodes: includeEpisodes
         });
         entities = listed;
         if (excludeSessionFromLongTerm) {
@@ -6745,7 +6816,8 @@ async function handleToolCall(name, args, deps) {
       const markdown = await client3.searchMemoryEntitiesMarkdown(workspaceId, query, {
         project_id: args.projectId || deps.getActiveProjectId() || undefined,
         type: args.type,
-        limit: args.limit
+        limit: args.limit,
+        include_episodes: Boolean(args.include_episodes)
       });
       const searchMemSession = getActiveMemorySession();
       if (searchMemSession) {
@@ -6762,7 +6834,8 @@ async function handleToolCall(name, args, deps) {
         workspace_id: workspaceId,
         project_id: args.projectId || deps.getActiveProjectId() || undefined,
         type: args.type,
-        limit: args.limit
+        limit: args.limit,
+        include_episodes: Boolean(args.include_episodes)
       });
       return markdown || "No entities found.";
     }

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`);
   }
@@ -2027,6 +2045,8 @@ class HarmonyApiClient {
       params.set("offset", String(options.offset));
     if (options.include_superseded)
       params.set("include_superseded", "true");
+    if (options.include_episodes)
+      params.set("include_episodes", "true");
     return this.request("GET", `/memory/entities?${params.toString()}`);
   }
   async getMemoryEntity(entityId) {
@@ -2042,7 +2062,8 @@ class HarmonyApiClient {
       const search = await this.searchMemoryEntities(options.workspaceId, options.query, {
         project_id: options.projectId,
         type: options.type?.length === 1 ? options.type[0] : undefined,
-        limit: fetchLimit
+        limit: fetchLimit,
+        include_episodes: options.includeEpisodes
       });
       entities = search.entities ?? [];
     } else {
@@ -2053,7 +2074,8 @@ class HarmonyApiClient {
         type: options.type?.length === 1 ? options.type[0] : undefined,
         tags: options.tags,
         min_confidence: options.minConfidence,
-        limit: fetchLimit
+        limit: fetchLimit,
+        include_episodes: options.includeEpisodes
       });
       entities = list.entities ?? [];
     }
@@ -2114,6 +2136,8 @@ class HarmonyApiClient {
       params.append("tags", tag);
     if (options?.include_superseded)
       params.set("include_superseded", "true");
+    if (options?.include_episodes)
+      params.set("include_episodes", "true");
     return this.request("GET", `/memory/search?${params.toString()}`);
   }
   async getVaultIndex(options) {
@@ -2125,6 +2149,8 @@ class HarmonyApiClient {
       params.set("type", options.type);
     if (options.limit !== undefined)
       params.set("limit", String(options.limit));
+    if (options.include_episodes)
+      params.set("include_episodes", "true");
     return this.request("GET", `/memory/index?${params.toString()}`);
   }
   async getVaultIndexMarkdown(options) {
@@ -2136,6 +2162,8 @@ class HarmonyApiClient {
       params.set("type", options.type);
     if (options.limit !== undefined)
       params.set("limit", String(options.limit));
+    if (options.include_episodes)
+      params.set("include_episodes", "true");
     return this.requestRaw("GET", `/memory/index?${params.toString()}`, undefined, {
       accept: "text/markdown"
     });
@@ -2193,6 +2221,8 @@ class HarmonyApiClient {
       params.set("type", options.type);
     if (options?.limit !== undefined)
       params.set("limit", String(options.limit));
+    if (options?.include_episodes)
+      params.set("include_episodes", "true");
     return this.requestRaw("GET", `/memory/search?${params.toString()}`, undefined, {
       accept: "text/markdown"
     });
@@ -2464,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;
@@ -2601,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(() => {});
     }
   }
@@ -4828,6 +4867,10 @@ var TOOLS = {
         include_superseded: {
           type: "boolean",
           description: "Include rows whose `superseded_at` is set (default false). Use when investigating supersede chains."
+        },
+        include_episodes: {
+          type: "boolean",
+          description: "Include agent-run episodes — the daemon's per-run implement/review captures (default false). Excluded by default so recall surfaces curated, durable memory. Set true to audit the agent's run history."
         }
       }
     }
@@ -5013,7 +5056,11 @@ var TOOLS = {
           type: "string",
           description: "Project ID (optional)"
         },
-        limit: { type: "number", description: "Max results (default: 20)" }
+        limit: { type: "number", description: "Max results (default: 20)" },
+        include_episodes: {
+          type: "boolean",
+          description: "Include agent-run episodes — the daemon's per-run captures (default false). Excluded by default so search surfaces curated memory."
+        }
       },
       required: ["query"]
     }
@@ -5054,6 +5101,10 @@ var TOOLS = {
         limit: {
           type: "number",
           description: "Max entities to return (default: 200)"
+        },
+        include_episodes: {
+          type: "boolean",
+          description: "Include agent-run episodes — the daemon's per-run captures (default false). Excluded by default so the index shows curated vault content, not run noise."
         }
       },
       required: []
@@ -6119,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 };
     }
@@ -6481,6 +6549,7 @@ async function handleToolCall(name, args, deps) {
       const topK = args.top_k;
       const budgetTokens = args.budget_tokens;
       const includeSuperseded = Boolean(args.include_superseded);
+      const includeEpisodes = Boolean(args.include_episodes);
       const queryText = args.query;
       const fetchLimit = Math.min(Math.max(requestedLimit ?? 20, topK ?? 0, 50), 200);
       const projectId = args.projectId || deps.getActiveProjectId() || undefined;
@@ -6497,7 +6566,8 @@ async function handleToolCall(name, args, deps) {
           type: args.type,
           limit: fetchLimit,
           tags: requestedTags && requestedTags.length > 0 ? requestedTags : undefined,
-          include_superseded: includeSuperseded
+          include_superseded: includeSuperseded,
+          include_episodes: includeEpisodes
         });
         entities = searchResult.entities ?? [];
         const minConfidence = args.minConfidence;
@@ -6520,7 +6590,8 @@ async function handleToolCall(name, args, deps) {
           tags: args.tags,
           min_confidence: args.minConfidence,
           limit: fetchLimit,
-          include_superseded: includeSuperseded
+          include_superseded: includeSuperseded,
+          include_episodes: includeEpisodes
         });
         entities = listed;
         if (excludeSessionFromLongTerm) {
@@ -6740,7 +6811,8 @@ async function handleToolCall(name, args, deps) {
       const markdown = await client3.searchMemoryEntitiesMarkdown(workspaceId, query, {
         project_id: args.projectId || deps.getActiveProjectId() || undefined,
         type: args.type,
-        limit: args.limit
+        limit: args.limit,
+        include_episodes: Boolean(args.include_episodes)
       });
       const searchMemSession = getActiveMemorySession();
       if (searchMemSession) {
@@ -6757,7 +6829,8 @@ async function handleToolCall(name, args, deps) {
         workspace_id: workspaceId,
         project_id: args.projectId || deps.getActiveProjectId() || undefined,
         type: args.type,
-        limit: args.limit
+        limit: args.limit,
+        include_episodes: Boolean(args.include_episodes)
       });
       return markdown || "No entities found.";
     }

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`);
   }
@@ -1479,6 +1497,8 @@ class HarmonyApiClient {
       params.set("offset", String(options.offset));
     if (options.include_superseded)
       params.set("include_superseded", "true");
+    if (options.include_episodes)
+      params.set("include_episodes", "true");
     return this.request("GET", `/memory/entities?${params.toString()}`);
   }
   async getMemoryEntity(entityId) {
@@ -1494,7 +1514,8 @@ class HarmonyApiClient {
       const search = await this.searchMemoryEntities(options.workspaceId, options.query, {
         project_id: options.projectId,
         type: options.type?.length === 1 ? options.type[0] : undefined,
-        limit: fetchLimit
+        limit: fetchLimit,
+        include_episodes: options.includeEpisodes
       });
       entities = search.entities ?? [];
     } else {
@@ -1505,7 +1526,8 @@ class HarmonyApiClient {
         type: options.type?.length === 1 ? options.type[0] : undefined,
         tags: options.tags,
         min_confidence: options.minConfidence,
-        limit: fetchLimit
+        limit: fetchLimit,
+        include_episodes: options.includeEpisodes
       });
       entities = list.entities ?? [];
     }
@@ -1566,6 +1588,8 @@ class HarmonyApiClient {
       params.append("tags", tag);
     if (options?.include_superseded)
       params.set("include_superseded", "true");
+    if (options?.include_episodes)
+      params.set("include_episodes", "true");
     return this.request("GET", `/memory/search?${params.toString()}`);
   }
   async getVaultIndex(options) {
@@ -1577,6 +1601,8 @@ class HarmonyApiClient {
       params.set("type", options.type);
     if (options.limit !== undefined)
       params.set("limit", String(options.limit));
+    if (options.include_episodes)
+      params.set("include_episodes", "true");
     return this.request("GET", `/memory/index?${params.toString()}`);
   }
   async getVaultIndexMarkdown(options) {
@@ -1588,6 +1614,8 @@ class HarmonyApiClient {
       params.set("type", options.type);
     if (options.limit !== undefined)
       params.set("limit", String(options.limit));
+    if (options.include_episodes)
+      params.set("include_episodes", "true");
     return this.requestRaw("GET", `/memory/index?${params.toString()}`, undefined, {
       accept: "text/markdown"
     });
@@ -1645,6 +1673,8 @@ class HarmonyApiClient {
       params.set("type", options.type);
     if (options?.limit !== undefined)
       params.set("limit", String(options.limit));
+    if (options?.include_episodes)
+      params.set("include_episodes", "true");
     return this.requestRaw("GET", `/memory/search?${params.toString()}`, undefined, {
       accept: "text/markdown"
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/mcp",
-  "version": "2.16.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;
@@ -1185,6 +1213,9 @@ export class HarmonyApiClient {
     limit?: number;
     offset?: number;
     include_superseded?: boolean;
+    // Opt in to agent-run episodes (default excluded, #677). Only the daemon's
+    // own rolling-episode lookup should set this.
+    include_episodes?: boolean;
   }): Promise<{ entities: unknown[]; count: number }> {
     const params = new URLSearchParams();
     params.set("workspace_id", options.workspace_id);
@@ -1201,6 +1232,7 @@ export class HarmonyApiClient {
     if (options.offset !== undefined)
       params.set("offset", String(options.offset));
     if (options.include_superseded) params.set("include_superseded", "true");
+    if (options.include_episodes) params.set("include_episodes", "true");
     return this.request("GET", `/memory/entities?${params.toString()}`);
   }
 
@@ -1249,6 +1281,9 @@ export class HarmonyApiClient {
     tags?: string[];
     minConfidence?: number;
     topK?: number;
+    // Opt in to agent-run episodes (default excluded server-side, #677). The
+    // daemon sets this when looking up its own rolling implement/review episode.
+    includeEpisodes?: boolean;
   }): Promise<{ entities: unknown[] }> {
     // Over-fetch beyond topK so client-side filters (multi-type, memory_tier,
     // tags) have headroom — matches the MCP server's recall path (server.ts).
@@ -1265,6 +1300,7 @@ export class HarmonyApiClient {
           project_id: options.projectId,
           type: options.type?.length === 1 ? options.type[0] : undefined,
           limit: fetchLimit,
+          include_episodes: options.includeEpisodes,
         },
       );
       entities = (search.entities ?? []) as Array<Record<string, unknown>>;
@@ -1277,6 +1313,7 @@ export class HarmonyApiClient {
         tags: options.tags,
         min_confidence: options.minConfidence,
         limit: fetchLimit,
+        include_episodes: options.includeEpisodes,
       });
       entities = (list.entities ?? []) as Array<Record<string, unknown>>;
     }
@@ -1360,6 +1397,7 @@ export class HarmonyApiClient {
       limit?: number;
       tags?: string[];
       include_superseded?: boolean;
+      include_episodes?: boolean;
     },
   ): Promise<{ entities: unknown[]; count: number }> {
     const params = new URLSearchParams();
@@ -1373,6 +1411,7 @@ export class HarmonyApiClient {
     // matches against the canonical `tags_normalized` column (#299).
     for (const tag of options?.tags ?? []) params.append("tags", tag);
     if (options?.include_superseded) params.set("include_superseded", "true");
+    if (options?.include_episodes) params.set("include_episodes", "true");
     return this.request("GET", `/memory/search?${params.toString()}`);
   }
 
@@ -1383,12 +1422,14 @@ export class HarmonyApiClient {
     project_id?: string;
     type?: string;
     limit?: number;
+    include_episodes?: boolean;
   }): Promise<{ entities: unknown[]; count: number }> {
     const params = new URLSearchParams();
     params.set("workspace_id", options.workspace_id);
     if (options.project_id) params.set("project_id", options.project_id);
     if (options.type) params.set("type", options.type);
     if (options.limit !== undefined) params.set("limit", String(options.limit));
+    if (options.include_episodes) params.set("include_episodes", "true");
     return this.request("GET", `/memory/index?${params.toString()}`);
   }
 
@@ -1397,12 +1438,14 @@ export class HarmonyApiClient {
     project_id?: string;
     type?: string;
     limit?: number;
+    include_episodes?: boolean;
   }): Promise<string> {
     const params = new URLSearchParams();
     params.set("workspace_id", options.workspace_id);
     if (options.project_id) params.set("project_id", options.project_id);
     if (options.type) params.set("type", options.type);
     if (options.limit !== undefined) params.set("limit", String(options.limit));
+    if (options.include_episodes) params.set("include_episodes", "true");
     return this.requestRaw(
       "GET",
       `/memory/index?${params.toString()}`,
@@ -1489,6 +1532,7 @@ export class HarmonyApiClient {
       project_id?: string;
       type?: string;
       limit?: number;
+      include_episodes?: boolean;
     },
   ): Promise<string> {
     const params = new URLSearchParams();
@@ -1498,6 +1542,7 @@ export class HarmonyApiClient {
     if (options?.type) params.set("type", options.type);
     if (options?.limit !== undefined)
       params.set("limit", String(options.limit));
+    if (options?.include_episodes) params.set("include_episodes", "true");
     return this.requestRaw(
       "GET",
       `/memory/search?${params.toString()}`,

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

@@ -1743,6 +1743,11 @@ export const TOOLS = {
           description:
             "Include rows whose `superseded_at` is set (default false). Use when investigating supersede chains.",
         },
+        include_episodes: {
+          type: "boolean",
+          description:
+            "Include agent-run episodes — the daemon's per-run implement/review captures (default false). Excluded by default so recall surfaces curated, durable memory. Set true to audit the agent's run history.",
+        },
       },
     },
   },
@@ -1934,6 +1939,11 @@ export const TOOLS = {
           description: "Project ID (optional)",
         },
         limit: { type: "number", description: "Max results (default: 20)" },
+        include_episodes: {
+          type: "boolean",
+          description:
+            "Include agent-run episodes — the daemon's per-run captures (default false). Excluded by default so search surfaces curated memory.",
+        },
       },
       required: ["query"],
     },
@@ -1978,6 +1988,11 @@ export const TOOLS = {
           type: "number",
           description: "Max entities to return (default: 200)",
         },
+        include_episodes: {
+          type: "boolean",
+          description:
+            "Include agent-run episodes — the daemon's per-run captures (default false). Excluded by default so the index shows curated vault content, not run noise.",
+        },
       },
       required: [],
     },
@@ -3474,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 };
     }
@@ -4108,6 +4159,8 @@ async function handleToolCall(
       const topK = args.top_k as number | undefined;
       const budgetTokens = args.budget_tokens as number | undefined;
       const includeSuperseded = Boolean(args.include_superseded);
+      // #677: agent-run episodes are excluded from recall by default; opt in.
+      const includeEpisodes = Boolean(args.include_episodes);
       const queryText = args.query as string | undefined;
 
       // Over-fetch when top_k is smaller than limit so the rescorer has
@@ -4166,6 +4219,7 @@ async function handleToolCall(
                 ? requestedTags
                 : undefined,
             include_superseded: includeSuperseded,
+            include_episodes: includeEpisodes,
           },
         );
         entities = (searchResult.entities ?? []) as any[];
@@ -4199,6 +4253,7 @@ async function handleToolCall(
           min_confidence: args.minConfidence as number | undefined,
           limit: fetchLimit,
           include_superseded: includeSuperseded,
+          include_episodes: includeEpisodes,
         });
         entities = listed as any[];
         if (excludeSessionFromLongTerm) {
@@ -4543,6 +4598,7 @@ async function handleToolCall(
             undefined,
           type: args.type as string | undefined,
           limit: args.limit as number | undefined,
+          include_episodes: Boolean(args.include_episodes),
         },
       );
 
@@ -4570,6 +4626,7 @@ async function handleToolCall(
           (args.projectId as string) || deps.getActiveProjectId() || undefined,
         type: args.type as string | undefined,
         limit: args.limit as number | undefined,
+        include_episodes: Boolean(args.include_episodes),
       });
       return markdown || "No entities found.";
     }