@gethmy/mcp 2.20.0 → 2.21.0

package/dist/cli.js

@@ -1386,6 +1386,14 @@ import {
   ReadResourceRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
+// ../harmony-shared/dist/agentStaleness.js
+var AGENT_HEARTBEAT_LIVENESS_MS = 5 * 60 * 1000;
+var AGENT_MILESTONE_LIVENESS_MS = 30 * 60 * 1000;
+var AGENT_SWEEP_DAEMON_MS = 30 * 60 * 1000;
+var AGENT_SWEEP_INTERACTIVE_MS = 2 * 60 * 60 * 1000;
+var AGENT_SWEEP_PAUSED_MS = 4 * 60 * 60 * 1000;
+var SWEPT_SESSION_WRITE_GRACE_MS = 60 * 60 * 1000;
+var ACTIVE_STATUSES = new Set(["working", "blocked", "waiting"]);
 // ../harmony-shared/dist/cardLinks.js
 var LINK_TYPE_INVERSES = {
   relates_to: "relates_to",
@@ -2556,11 +2564,14 @@ async function trackActivity(cardId, options) {
     await autoEndSession(scope, client3, otherCardId, "completed");
   }
   try {
-    await client3.startAgentSession(cardId, {
+    const started = await client3.startAgentSession(cardId, {
       agentIdentifier,
       agentName,
-      status: "working"
+      status: "working",
+      implicitCreate: true
     });
+    if (started?.session === null)
+      return;
   } catch {}
   scope.sessions.set(cardId, {
     cardId,
@@ -3798,7 +3809,8 @@ async function flushMemoryActions(client3, cardId) {
     await client3.updateAgentProgress(cardId, {
       agentIdentifier: session.agentIdentifier,
       agentName: session.agentName,
-      recentActions: session.allActions
+      recentActions: session.allActions,
+      implicitCreate: true
     });
     session.dirty = false;
   } catch (err) {
@@ -4190,7 +4202,7 @@ var TOOLS = {
     }
   },
   harmony_upload: {
-    description: 'Upload a file in one call. `target: "card_attachment"` attaches a file to a card ' + "(max 5MB; PNG/JPEG/GIF/WebP/HEIC/HEIF/PDF/DOC(X)/XLS(X)/TXT/CSV) — requires cardId. " + '`target: "artifact"` hosts a self-contained HTML doc (text/html, max 2MB) linked to ' + "exactly one of cardId/planId/workspaceId, rendered in-app in a sandboxed iframe. Provide " + "the bytes as `filePath` (local, direct-to-storage) or `base64Data` (small-file fallback). " + "Returns the attachment/artifact + a signed URL (artifact: use harmony_share_artifact for a " + "public link). Large files on the hosted MCP server: use harmony_request_upload_url + " + "harmony_finalize_upload instead.",
+    description: 'Upload a file in one call. `target: "card_attachment"` attaches a file to a card ' + "(max 5MB; PNG/JPEG/GIF/WebP/HEIC/HEIF/PDF/DOC(X)/XLS(X)/TXT/CSV) — requires cardId. " + '`target: "artifact"` hosts a self-contained HTML doc (text/html, max 2MB) linked to ' + "exactly one of cardId/planId/workspaceId, rendered in-app in a sandboxed iframe. Provide " + "the bytes as `filePath` (local, direct-to-storage) or `base64Data` (small-file fallback). " + "Returns the attachment/artifact. An artifact comes back with TWO URLs, and the difference " + "matters: `app_url` is the durable in-app permalink — this is the one to hand a person, it " + "never expires and requires them to log in as a workspace member — while `signed_url` only " + "renders the document in-app and dies within the hour, so never pass it on. To share with " + "someone OUTSIDE the workspace, mint a public link with harmony_share_artifact. Large files " + "on the hosted MCP server: use harmony_request_upload_url + harmony_finalize_upload instead.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4276,7 +4288,7 @@ var TOOLS = {
     }
   },
   harmony_finalize_upload: {
-    description: "Step 2 of the upload handshake. After PUTting the bytes to the signed uploadUrl, call this " + "with the storagePath to validate and register. The server re-downloads the object and " + "enforces size + content-type (magic-byte sniff, never the declared type) + an optional " + 'sha256 integrity check, deleting and failing on any mismatch. `target: "card_attachment"` ' + '(cardId, storagePath, fileName) or `target: "artifact"` (storagePath + the same one of ' + "cardId/planId/workspaceId used for the upload URL). Returns the attachment/artifact + a signed URL.",
+    description: "Step 2 of the upload handshake. After PUTting the bytes to the signed uploadUrl, call this " + "with the storagePath to validate and register. The server re-downloads the object and " + "enforces size + content-type (magic-byte sniff, never the declared type) + an optional " + 'sha256 integrity check, deleting and failing on any mismatch. `target: "card_attachment"` ' + '(cardId, storagePath, fileName) or `target: "artifact"` (storagePath + the same one of ' + "cardId/planId/workspaceId used for the upload URL). Returns the attachment/artifact + a signed " + "URL; an artifact also carries `app_url`, the durable in-app permalink — hand that one to a " + "person, never the short-lived `signed_url`.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4330,7 +4342,7 @@ var TOOLS = {
     }
   },
   harmony_share_artifact: {
-    description: "Create a public, unauthenticated share link for a hosted artifact. Anyone with the link can view the rendered HTML without a Harmony account. Returns the share token and the full public URL.",
+    description: "Create a public, unauthenticated share link for a hosted artifact. Anyone with the link can view the rendered HTML without a Harmony account. Returns the share token and the full public URL. Only needed for a recipient OUTSIDE the workspace — for a teammate, hand over the `app_url` the upload already returned instead of exposing the document publicly.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4651,7 +4663,7 @@ var TOOLS = {
     }
   },
   harmony_update_agent_progress: {
-    description: "Update progress on an active agent session. Use to report progress percentage, current task, blockers, or status changes.",
+    description: "Update progress on an active agent session. Use to report progress percentage, current task, blockers, or status changes. Check the reply: `session: null` with `stopped: true` means a human stopped this card's run, so reporting progress will no longer open a session here (card #770) — stop work if you were mid-run, and read `recovery` for the one legitimate way back. Otherwise a session is always returned: this call opens one if none is live.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4736,7 +4748,7 @@ var TOOLS = {
     }
   },
   harmony_get_pending_messages: {
-    description: "Drain queued steering messages a teammate sent to your live agent session (card #473). Call at your progress checkpoints with the session id from harmony_start_agent_session and the highest seq you've already consumed; returns user messages with seq > sinceSeq, oldest first. Fold them into your next step and advance sinceSeq to the largest returned seq so each is handled exactly once.",
+    description: "Drain queued steering messages a teammate sent to your live agent session, and check whether that session is still live (cards #473, #770). Call at your progress checkpoints with the session id from harmony_start_agent_session and the highest seq you've already consumed; returns user messages with seq > sinceSeq, oldest first. Fold them into your next step and advance sinceSeq to the largest returned seq so each is handled exactly once. Two liveness flags come back and mean different things: `stopped` (a human pressed Stop) is TERMINAL — stop work at once, make no further edits, commits, pushes, or progress writes, don't move the card, and report what you had done and where any uncommitted work lives. `sessionStale` only means your session id went stale (usually the 30-minute inactivity cron) — nobody stopped you, so do NOT abandon the work: open a fresh session with harmony_start_agent_session and carry on with its new id. (Distinct from harmony_move_card's `sessionEnded`, which means the move deliberately closed your session.)",
     inputSchema: {
       type: "object",
       properties: {
@@ -5583,7 +5595,7 @@ function registerHandlers(server, deps) {
       trackActivity(cardIdArg, {
         autoStart: isAutoStartTrigger,
         client: deps.getClient(),
-        clientInfo: cv ? { name: cv.name, version: cv.version } : undefined,
+        clientInfo: cv ? { name: cv.name, version: cv.version } : deps.getClientInfo?.() ?? undefined,
         scopeId: deps.getScopeId?.()
       }).catch(() => {});
     }
@@ -5598,7 +5610,7 @@ function registerHandlers(server, deps) {
             trackActivity(resolvedCardId, {
               autoStart: true,
               client: deps.getClient(),
-              clientInfo: cv ? { name: cv.name, version: cv.version } : undefined,
+              clientInfo: cv ? { name: cv.name, version: cv.version } : deps.getClientInfo?.() ?? undefined,
               scopeId: deps.getScopeId?.()
             }).catch(() => {});
           }
@@ -6454,8 +6466,12 @@ ${options}
         blockers: args.blockers,
         estimatedMinutesRemaining: optionalNonNegativeNumberArg(args.estimatedMinutesRemaining, "estimatedMinutesRemaining"),
         ...mergedRecentActions && { recentActions: mergedRecentActions },
-        ...runActivity.length > 0 && { runActivity }
+        ...runActivity.length > 0 && { runActivity },
+        implicitCreate: true
       });
+      if (result.session === null) {
+        untrack(cardId, deps.getScopeId?.());
+      }
       return { success: true, midSessionLearnings: 0, ...result };
     }
     case "harmony_end_agent_session": {
@@ -6465,7 +6481,9 @@ ${options}
       const endProgressPercent = optionalPercentArg(args.progressPercent, "progressPercent");
       await flushMemoryActions(client3, cardId);
       cleanupMemorySession(cardId);
-      let result = { session: null };
+      let result = {
+        session: null
+      };
       let sessionEndError = null;
       try {
         result = await client3.endAgentSession(cardId, {
@@ -6515,6 +6533,29 @@ ${options}
       const sessionId = z.string().min(1).parse(args.sessionId);
       const sinceSeq = args.sinceSeq !== undefined ? z.number().int().min(0).parse(args.sinceSeq) : 0;
       const result = await client3.getPendingMessages(cardId, sessionId, sinceSeq);
+      const stoppedByHuman = result.session?.stoppedByHuman === true;
+      const ended = result.session?.ended === true;
+      if (ended || stoppedByHuman) {
+        untrack(cardId, deps.getScopeId?.());
+      }
+      if (stoppedByHuman) {
+        return {
+          success: true,
+          ...result,
+          stopped: true,
+          stopReason: "human_stopped",
+          instruction: "A human stopped this run — stop work now. Make no further edits, commits, pushes, or progress writes, and do not move the card. Commit any uncommitted work in place so it isn't lost, then report to the user what you completed, what is unfinished, and the branch holding it."
+        };
+      }
+      if (ended) {
+        return {
+          success: true,
+          ...result,
+          sessionStale: true,
+          staleReason: result.session?.status,
+          instruction: 'This session id is no longer live (it was closed as "' + (result.session?.status ?? "missing") + '") — but nobody stopped you. Do NOT abandon the work. Open a fresh session with harmony_start_agent_session, use its new id for later polls, and carry on.'
+        };
+      }
       return { success: true, ...result };
     }
     case "harmony_generate_prompt": {
@@ -8546,14 +8587,29 @@ ${summary}`);
 
 This project uses Harmony for task management. When working on tasks:
 
+## Agent identity — always identify as yourself
+
+Every \`harmony_start_agent_session\` call passes \`agentIdentifier\` + \`agentName\`. **Use your own
+identity, never a hardcoded one from this file.** AGENTS.md is a cross-runtime convention file, so
+more than one kind of agent will read it; the board shows agents as teammates, and a session
+attributed to the wrong runtime misattributes the work in front of the whole team.
+
+- \`agentIdentifier\` — a stable kebab-case id for the runtime you actually are
+- \`agentName\` — its human-readable name
+
+Known values: \`claude-code\` / "Claude Code", \`codex\` / "OpenAI Codex", \`cursor\` / "Cursor",
+\`claude-desktop\` / "Claude Desktop". If you are a runtime not listed here, use your own name rather
+than borrowing the closest entry.
+
 ## Starting Work on a Card
 
 When given a card reference (e.g., #42 or a card name), follow this workflow:
 
-1. Use \`harmony_get_card_by_short_id\` or \`harmony_search_cards\` to find the card
+1. Use \`harmony_get_card\` or \`harmony_search_cards\` to find the card
 2. Move the card to "In Progress" using \`harmony_move_card\`
 3. Add the "agent" label using \`harmony_add_label_to_card\`
-4. Start a session with \`harmony_start_agent_session\` (agentIdentifier: "codex", agentName: "OpenAI Codex")
+4. Start a session with \`harmony_start_agent_session\`, passing **your own** \`agentIdentifier\` +
+   \`agentName\` (see "Agent identity" above)
 5. Show the card details to the user
 6. Use \`harmony_generate_prompt\` to get guidance, then implement the solution
 7. Update progress periodically with \`harmony_update_agent_progress\`
@@ -8564,7 +8620,8 @@ When given a card reference (e.g., #42 or a card name), follow this workflow:
 Before implementing a plan or feature, check if it maps to an existing Harmony card:
 
 1. Use \`harmony_search_cards\` with keywords from the task description
-2. If a match is found, call \`harmony_start_agent_session\` (agentIdentifier: "claude-code", agentName: "Claude Code", moveToColumn: "In Progress", addLabels: ["agent"])
+2. If a match is found, call \`harmony_start_agent_session\` with **your own** \`agentIdentifier\` +
+   \`agentName\` (see "Agent identity" above), plus \`moveToColumn: "In Progress"\`, \`addLabels: ["agent"]\`
 3. Update progress with \`harmony_update_agent_progress\` at milestones
 4. When done, call \`harmony_end_agent_session\` with status: "completed", moveToColumn: "Review"
 

package/dist/index.js

@@ -1381,6 +1381,14 @@ import {
   ReadResourceRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
+// ../harmony-shared/dist/agentStaleness.js
+var AGENT_HEARTBEAT_LIVENESS_MS = 5 * 60 * 1000;
+var AGENT_MILESTONE_LIVENESS_MS = 30 * 60 * 1000;
+var AGENT_SWEEP_DAEMON_MS = 30 * 60 * 1000;
+var AGENT_SWEEP_INTERACTIVE_MS = 2 * 60 * 60 * 1000;
+var AGENT_SWEEP_PAUSED_MS = 4 * 60 * 60 * 1000;
+var SWEPT_SESSION_WRITE_GRACE_MS = 60 * 60 * 1000;
+var ACTIVE_STATUSES = new Set(["working", "blocked", "waiting"]);
 // ../harmony-shared/dist/cardLinks.js
 var LINK_TYPE_INVERSES = {
   relates_to: "relates_to",
@@ -2551,11 +2559,14 @@ async function trackActivity(cardId, options) {
     await autoEndSession(scope, client3, otherCardId, "completed");
   }
   try {
-    await client3.startAgentSession(cardId, {
+    const started = await client3.startAgentSession(cardId, {
       agentIdentifier,
       agentName,
-      status: "working"
+      status: "working",
+      implicitCreate: true
     });
+    if (started?.session === null)
+      return;
   } catch {}
   scope.sessions.set(cardId, {
     cardId,
@@ -3793,7 +3804,8 @@ async function flushMemoryActions(client3, cardId) {
     await client3.updateAgentProgress(cardId, {
       agentIdentifier: session.agentIdentifier,
       agentName: session.agentName,
-      recentActions: session.allActions
+      recentActions: session.allActions,
+      implicitCreate: true
     });
     session.dirty = false;
   } catch (err) {
@@ -4185,7 +4197,7 @@ var TOOLS = {
     }
   },
   harmony_upload: {
-    description: 'Upload a file in one call. `target: "card_attachment"` attaches a file to a card ' + "(max 5MB; PNG/JPEG/GIF/WebP/HEIC/HEIF/PDF/DOC(X)/XLS(X)/TXT/CSV) — requires cardId. " + '`target: "artifact"` hosts a self-contained HTML doc (text/html, max 2MB) linked to ' + "exactly one of cardId/planId/workspaceId, rendered in-app in a sandboxed iframe. Provide " + "the bytes as `filePath` (local, direct-to-storage) or `base64Data` (small-file fallback). " + "Returns the attachment/artifact + a signed URL (artifact: use harmony_share_artifact for a " + "public link). Large files on the hosted MCP server: use harmony_request_upload_url + " + "harmony_finalize_upload instead.",
+    description: 'Upload a file in one call. `target: "card_attachment"` attaches a file to a card ' + "(max 5MB; PNG/JPEG/GIF/WebP/HEIC/HEIF/PDF/DOC(X)/XLS(X)/TXT/CSV) — requires cardId. " + '`target: "artifact"` hosts a self-contained HTML doc (text/html, max 2MB) linked to ' + "exactly one of cardId/planId/workspaceId, rendered in-app in a sandboxed iframe. Provide " + "the bytes as `filePath` (local, direct-to-storage) or `base64Data` (small-file fallback). " + "Returns the attachment/artifact. An artifact comes back with TWO URLs, and the difference " + "matters: `app_url` is the durable in-app permalink — this is the one to hand a person, it " + "never expires and requires them to log in as a workspace member — while `signed_url` only " + "renders the document in-app and dies within the hour, so never pass it on. To share with " + "someone OUTSIDE the workspace, mint a public link with harmony_share_artifact. Large files " + "on the hosted MCP server: use harmony_request_upload_url + harmony_finalize_upload instead.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4271,7 +4283,7 @@ var TOOLS = {
     }
   },
   harmony_finalize_upload: {
-    description: "Step 2 of the upload handshake. After PUTting the bytes to the signed uploadUrl, call this " + "with the storagePath to validate and register. The server re-downloads the object and " + "enforces size + content-type (magic-byte sniff, never the declared type) + an optional " + 'sha256 integrity check, deleting and failing on any mismatch. `target: "card_attachment"` ' + '(cardId, storagePath, fileName) or `target: "artifact"` (storagePath + the same one of ' + "cardId/planId/workspaceId used for the upload URL). Returns the attachment/artifact + a signed URL.",
+    description: "Step 2 of the upload handshake. After PUTting the bytes to the signed uploadUrl, call this " + "with the storagePath to validate and register. The server re-downloads the object and " + "enforces size + content-type (magic-byte sniff, never the declared type) + an optional " + 'sha256 integrity check, deleting and failing on any mismatch. `target: "card_attachment"` ' + '(cardId, storagePath, fileName) or `target: "artifact"` (storagePath + the same one of ' + "cardId/planId/workspaceId used for the upload URL). Returns the attachment/artifact + a signed " + "URL; an artifact also carries `app_url`, the durable in-app permalink — hand that one to a " + "person, never the short-lived `signed_url`.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4325,7 +4337,7 @@ var TOOLS = {
     }
   },
   harmony_share_artifact: {
-    description: "Create a public, unauthenticated share link for a hosted artifact. Anyone with the link can view the rendered HTML without a Harmony account. Returns the share token and the full public URL.",
+    description: "Create a public, unauthenticated share link for a hosted artifact. Anyone with the link can view the rendered HTML without a Harmony account. Returns the share token and the full public URL. Only needed for a recipient OUTSIDE the workspace — for a teammate, hand over the `app_url` the upload already returned instead of exposing the document publicly.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4646,7 +4658,7 @@ var TOOLS = {
     }
   },
   harmony_update_agent_progress: {
-    description: "Update progress on an active agent session. Use to report progress percentage, current task, blockers, or status changes.",
+    description: "Update progress on an active agent session. Use to report progress percentage, current task, blockers, or status changes. Check the reply: `session: null` with `stopped: true` means a human stopped this card's run, so reporting progress will no longer open a session here (card #770) — stop work if you were mid-run, and read `recovery` for the one legitimate way back. Otherwise a session is always returned: this call opens one if none is live.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4731,7 +4743,7 @@ var TOOLS = {
     }
   },
   harmony_get_pending_messages: {
-    description: "Drain queued steering messages a teammate sent to your live agent session (card #473). Call at your progress checkpoints with the session id from harmony_start_agent_session and the highest seq you've already consumed; returns user messages with seq > sinceSeq, oldest first. Fold them into your next step and advance sinceSeq to the largest returned seq so each is handled exactly once.",
+    description: "Drain queued steering messages a teammate sent to your live agent session, and check whether that session is still live (cards #473, #770). Call at your progress checkpoints with the session id from harmony_start_agent_session and the highest seq you've already consumed; returns user messages with seq > sinceSeq, oldest first. Fold them into your next step and advance sinceSeq to the largest returned seq so each is handled exactly once. Two liveness flags come back and mean different things: `stopped` (a human pressed Stop) is TERMINAL — stop work at once, make no further edits, commits, pushes, or progress writes, don't move the card, and report what you had done and where any uncommitted work lives. `sessionStale` only means your session id went stale (usually the 30-minute inactivity cron) — nobody stopped you, so do NOT abandon the work: open a fresh session with harmony_start_agent_session and carry on with its new id. (Distinct from harmony_move_card's `sessionEnded`, which means the move deliberately closed your session.)",
     inputSchema: {
       type: "object",
       properties: {
@@ -5578,7 +5590,7 @@ function registerHandlers(server, deps) {
       trackActivity(cardIdArg, {
         autoStart: isAutoStartTrigger,
         client: deps.getClient(),
-        clientInfo: cv ? { name: cv.name, version: cv.version } : undefined,
+        clientInfo: cv ? { name: cv.name, version: cv.version } : deps.getClientInfo?.() ?? undefined,
         scopeId: deps.getScopeId?.()
       }).catch(() => {});
     }
@@ -5593,7 +5605,7 @@ function registerHandlers(server, deps) {
             trackActivity(resolvedCardId, {
               autoStart: true,
               client: deps.getClient(),
-              clientInfo: cv ? { name: cv.name, version: cv.version } : undefined,
+              clientInfo: cv ? { name: cv.name, version: cv.version } : deps.getClientInfo?.() ?? undefined,
               scopeId: deps.getScopeId?.()
             }).catch(() => {});
           }
@@ -6449,8 +6461,12 @@ ${options}
         blockers: args.blockers,
         estimatedMinutesRemaining: optionalNonNegativeNumberArg(args.estimatedMinutesRemaining, "estimatedMinutesRemaining"),
         ...mergedRecentActions && { recentActions: mergedRecentActions },
-        ...runActivity.length > 0 && { runActivity }
+        ...runActivity.length > 0 && { runActivity },
+        implicitCreate: true
       });
+      if (result.session === null) {
+        untrack(cardId, deps.getScopeId?.());
+      }
       return { success: true, midSessionLearnings: 0, ...result };
     }
     case "harmony_end_agent_session": {
@@ -6460,7 +6476,9 @@ ${options}
       const endProgressPercent = optionalPercentArg(args.progressPercent, "progressPercent");
       await flushMemoryActions(client3, cardId);
       cleanupMemorySession(cardId);
-      let result = { session: null };
+      let result = {
+        session: null
+      };
       let sessionEndError = null;
       try {
         result = await client3.endAgentSession(cardId, {
@@ -6510,6 +6528,29 @@ ${options}
       const sessionId = z.string().min(1).parse(args.sessionId);
       const sinceSeq = args.sinceSeq !== undefined ? z.number().int().min(0).parse(args.sinceSeq) : 0;
       const result = await client3.getPendingMessages(cardId, sessionId, sinceSeq);
+      const stoppedByHuman = result.session?.stoppedByHuman === true;
+      const ended = result.session?.ended === true;
+      if (ended || stoppedByHuman) {
+        untrack(cardId, deps.getScopeId?.());
+      }
+      if (stoppedByHuman) {
+        return {
+          success: true,
+          ...result,
+          stopped: true,
+          stopReason: "human_stopped",
+          instruction: "A human stopped this run — stop work now. Make no further edits, commits, pushes, or progress writes, and do not move the card. Commit any uncommitted work in place so it isn't lost, then report to the user what you completed, what is unfinished, and the branch holding it."
+        };
+      }
+      if (ended) {
+        return {
+          success: true,
+          ...result,
+          sessionStale: true,
+          staleReason: result.session?.status,
+          instruction: 'This session id is no longer live (it was closed as "' + (result.session?.status ?? "missing") + '") — but nobody stopped you. Do NOT abandon the work. Open a fresh session with harmony_start_agent_session, use its new id for later polls, and carry on.'
+        };
+      }
       return { success: true, ...result };
     }
     case "harmony_generate_prompt": {

package/dist/lib/api-client.js

@@ -833,6 +833,14 @@ var init_prompt_builder = __esm(() => {
     execute: `EXECUTE MODE: Implement this task completely. Write production-ready code following best practices. Include necessary tests and documentation.`
   };
 });
+// ../harmony-shared/dist/agentStaleness.js
+var AGENT_HEARTBEAT_LIVENESS_MS = 5 * 60 * 1000;
+var AGENT_MILESTONE_LIVENESS_MS = 30 * 60 * 1000;
+var AGENT_SWEEP_DAEMON_MS = 30 * 60 * 1000;
+var AGENT_SWEEP_INTERACTIVE_MS = 2 * 60 * 60 * 1000;
+var AGENT_SWEEP_PAUSED_MS = 4 * 60 * 60 * 1000;
+var SWEPT_SESSION_WRITE_GRACE_MS = 60 * 60 * 1000;
+var ACTIVE_STATUSES = new Set(["working", "blocked", "waiting"]);
 // ../harmony-shared/dist/cardLinks.js
 var LINK_TYPE_INVERSES = {
   relates_to: "relates_to",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/mcp",
-  "version": "2.20.0",
+  "version": "2.21.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 src/__tests__/auto-session.test.ts src/__tests__/setup-confirm.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 src/__tests__/remote-routing.test.ts src/__tests__/setup-confirm.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

@@ -513,6 +513,12 @@ export class HarmonyApiClient {
     userId: string;
     source: "api_key" | "oauth" | "jwt";
     workspaceId: string | null;
+    /**
+     * The OAuth grant behind the credential — stable across refresh rotation,
+     * null for api_key/jwt auth (#774). Optional because this client may be
+     * talking to a harmony-api deployed before the field existed.
+     */
+    grantId?: string | null;
   }> {
     return this.request("GET", "/auth/context");
   }
@@ -1064,27 +1070,58 @@ export class HarmonyApiClient {
       agentId?: string | null;
       /** Advertise that this session polls for queued steering messages (card #473). */
       steerable?: boolean;
+      /**
+       * The start is a side effect of a trigger tool (auto-session), not a
+       * deliberate `/hmy` start. Barred on a card whose last session a human
+       * cancelled, so a surviving client can't resurrect it (#770).
+       */
+      implicitCreate?: boolean;
       status?: "working" | "blocked" | "paused" | "completed";
       progressPercent?: number;
       currentTask?: string;
       blockers?: string[];
       estimatedMinutesRemaining?: number;
     },
-  ): Promise<{ session: unknown; created: boolean }> {
+  ): Promise<{
+    session: unknown;
+    created: boolean;
+    stopped?: boolean;
+    stopReason?: "human_stopped";
+  }> {
     return this.request("POST", `/cards/${cardId}/agent-context`, data);
   }
 
   /**
-   * Drain queued `user_message` steering events for a session (card #473).
+   * Drain queued `user_message` steering events for a session (card #473), and
+   * learn whether that session is still live (card #770).
+   *
    * Wraps the existing `GET /cards/{id}/agent-messages` endpoint that the daemon
    * already polls — exposed so MCP/human sessions (e.g. /hmy) can consume steering
    * at their checkpoints. Returns messages with `seq > sinceSeq`, oldest first.
+   *
+   * `session.stoppedByHuman` is the durable half of Stop: the ephemeral
+   * `agent_command` broadcast has no consumer for `agent_id == null` sessions, so
+   * this poll is where such a client finds out it was stopped.
+   *
+   * `ended` is the weaker fact — the row is no longer live, most often because the
+   * 30-minute stale cron closed it, which is NOT a stop. Only `stoppedByHuman` is
+   * terminal. `session` is absent on an older server, or when the liveness read
+   * itself failed; absent means "assume live".
    */
   async getPendingMessages(
     cardId: string,
     sessionId: string,
     sinceSeq: number,
-  ): Promise<{ messages: unknown[] }> {
+  ): Promise<{
+    messages: unknown[];
+    session?: {
+      id: string;
+      status: string;
+      endedAt: string | null;
+      ended: boolean;
+      stoppedByHuman: boolean;
+    };
+  }> {
     const params = new URLSearchParams();
     params.set("sessionId", sessionId);
     params.set("sinceSeq", String(sinceSeq));
@@ -1144,8 +1181,24 @@ export class HarmonyApiClient {
        * report on a session but must never bring one back from the dead (#696).
        */
       noCreate?: boolean;
+      /**
+       * This write only meant to REPORT progress — creating a session is a side
+       * effect, not the intent. Weaker than `noCreate` (an agent that never called
+       * `start_agent_session` still gets one), but permanently barred on a card
+       * whose last session a human cancelled, where the #663 cooldown only
+       * deferred the respawn by 10 minutes (#770). Reply carries `stopped: true`.
+       */
+      implicitCreate?: boolean;
     },
-  ): Promise<{ session: unknown; created: boolean }> {
+  ): Promise<{
+    session: unknown;
+    created: boolean;
+    /** Set when the write was refused because a human stopped this card's run. */
+    stopped?: boolean;
+    stopReason?: "human_stopped";
+    /** How to legitimately work this card again (an explicit start). */
+    recovery?: string;
+  }> {
     return this.request("POST", `/cards/${cardId}/agent-context`, data);
   }
 
@@ -1184,7 +1237,18 @@ export class HarmonyApiClient {
       attemptNumber?: number;
       maxAttempts?: number;
     },
-  ): Promise<{ session: unknown }> {
+  ): Promise<{
+    session: unknown;
+    /**
+     * Whether this call actually wrote a terminal state (#769). `false` — with
+     * `session: null` — means the response succeeded but changed nothing: there
+     * was no live session (`no_active_session`), or a concurrent caller ended
+     * the same one first (`concurrently_ended`). Older servers omit both fields,
+     * so treat `undefined` as "unknown" and fall back to `session !== null`.
+     */
+    ended?: boolean;
+    reason?: "no_active_session" | "concurrently_ended";
+  }> {
     return this.request("DELETE", `/cards/${cardId}/agent-context`, data);
   }
 

package/src/auto-session.ts

@@ -130,10 +130,20 @@ const CHECK_INTERVAL_MS = 60 * 1000; // 60 seconds
  * 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.
+ * cron's 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.
+ *
+ * The cron's threshold for the interactive sessions this manages is **2 hours**,
+ * not the 30 minutes this comment originally cited (card #771 —
+ * `AGENT_SWEEP_INTERACTIVE_MS` in `packages/harmony-shared/src/agentStaleness.ts`;
+ * 30 minutes still applies to daemon runs, which heartbeat independently). The
+ * old pairing is what produced the bug: this window expiring at 25 minutes plus a
+ * flat 30-minute sweep gave a *working* agent only ~55 minutes of total silence,
+ * so one long verify/review phase got its live session closed as failed. Keeping
+ * this window short is still correct — it is what lets a finished-but-unclosed
+ * session be reaped at all — but the reaping now happens on a window sized for
+ * real work rather than one that a single gate run can outlast.
  */
 export const HEARTBEAT_ACTIVITY_WINDOW_MS = 25 * 60 * 1000; // 25 minutes
 
@@ -274,13 +284,22 @@ export async function trackActivity(
     await autoEndSession(scope, client, otherCardId, "completed");
   }
 
-  // Start a new auto-session
+  // Start a new auto-session. `implicitCreate` because this start is a side
+  // effect of a trigger tool, not a deliberate `harmony_start_agent_session`: on
+  // a card whose last session a human cancelled, the server refuses it outright
+  // rather than letting a surviving client walk the run back to life one cooldown
+  // later (card #770). An explicit `/hmy` re-run is unaffected — it starts the
+  // session by name and only faces the 10-minute #663 window.
   try {
-    await client.startAgentSession(cardId, {
+    const started = await client.startAgentSession(cardId, {
       agentIdentifier,
       agentName,
       status: "working",
+      implicitCreate: true,
     });
+    // Refused: don't track it locally either, or the sweep would heartbeat a
+    // session that does not exist and `checkInactivity` would later "end" it.
+    if (started?.session === null) return;
   } catch {
     // Session start failed (might already have one), still track locally
   }