@gethmy/mcp 2.17.0 → 2.18.0

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`);
   }
@@ -1851,6 +1869,10 @@ class HarmonyApiClient {
   async getCardByShortId(projectId, shortId) {
     return this.request("GET", `/projects/${projectId}/cards/${shortId}`);
   }
+  async resolveCardByShortId(shortId, preferredProjectId) {
+    const qs = preferredProjectId ? `?preferred_project_id=${encodeURIComponent(preferredProjectId)}` : "";
+    return this.request("GET", `/cards/resolve/${shortId}${qs}`);
+  }
   async bulkGetCards(projectId, shortIds) {
     return this.request("POST", `/projects/${projectId}/cards/bulk-get`, {
       shortIds
@@ -2481,6 +2503,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 +2641,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(() => {});
     }
   }
@@ -5736,9 +5767,51 @@ async function handleToolCall(name, args, deps) {
       }
       if (hasShortId) {
         const shortId = z.number().int().positive().parse(args.shortId);
-        const projectId = args.projectId || getProjectId();
-        const result2 = await client3.getCardByShortId(projectId, shortId);
-        return { success: true, ...result2 };
+        const explicitProjectId = args.projectId;
+        if (explicitProjectId) {
+          const result2 = await client3.getCardByShortId(explicitProjectId, shortId);
+          return { success: true, ...result2 };
+        }
+        const activeProjectId = deps.getActiveProjectId();
+        const resolved = await client3.resolveCardByShortId(shortId, activeProjectId);
+        if (resolved.kind === "found") {
+          const cardTitle = resolved.card?.title ?? `#${shortId}`;
+          const where = resolved.project.workspaceName ? `project "${resolved.project.name ?? resolved.project.id}" (workspace "${resolved.project.workspaceName}")` : `project "${resolved.project.name ?? resolved.project.id}"`;
+          const established = activeProjectId == null;
+          if (established) {
+            deps.setActiveProject(resolved.project.id);
+          }
+          return {
+            success: true,
+            card: resolved.card,
+            resolvedProject: resolved.project,
+            activeProjectId: resolved.project.id,
+            note: established ? `Resolved #${shortId} → "${cardTitle}" in ${where}. No active project was set — set to this for follow-up references.` : `Resolved #${shortId} → "${cardTitle}" in ${where} (your active project).`
+          };
+        }
+        if (resolved.kind === "not_in_preferred") {
+          const list = resolved.candidates.map((c) => `  • "${c.title}" — project "${c.projectName ?? c.projectId}"${c.workspaceName ? ` / workspace "${c.workspaceName}"` : ""} (projectId: ${c.projectId})`).join(`
+`);
+          throw new Error(`#${shortId} is not in your active project (projectId: ${resolved.preferredProjectId}). ` + `It exists in ${resolved.candidates.length} other project(s) you can access:
+${list}
+
+` + `Switch with harmony_set_project_context, or pass an explicit projectId to fetch it directly.`);
+        }
+        if (resolved.kind === "ambiguous") {
+          const list = resolved.candidates.map((c) => `  • "${c.title}" — project "${c.projectName ?? c.projectId}"${c.workspaceName ? ` / workspace "${c.workspaceName}"` : ""} (projectId: ${c.projectId})`).join(`
+`);
+          return {
+            success: true,
+            needsDisambiguation: true,
+            shortId,
+            candidates: resolved.candidates,
+            message: `#${shortId} exists in ${resolved.candidates.length} projects you can access:
+${list}
+
+` + `Ask which one is meant, then re-fetch with an explicit projectId ` + `(or call harmony_set_project_context first).`
+          };
+        }
+        throw new Error(resolved.searchedProjectCount === 0 ? `#${shortId} can't be resolved: no project is accessible to this connection. ` + `Check the workspace this connection is authorized for with harmony_list_workspaces.` : `Card #${shortId} was not found in any of the ${resolved.searchedProjectCount} ` + `project(s) across ${resolved.searchedWorkspaceCount} workspace(s) this connection can access. ` + `Use harmony_list_projects to see them, or pass an explicit projectId.`);
       }
       const cardId = z.string().uuid().parse(args.cardId);
       const result = await client3.getCard(cardId);
@@ -6148,6 +6221,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`);
   }
@@ -1846,6 +1864,10 @@ class HarmonyApiClient {
   async getCardByShortId(projectId, shortId) {
     return this.request("GET", `/projects/${projectId}/cards/${shortId}`);
   }
+  async resolveCardByShortId(shortId, preferredProjectId) {
+    const qs = preferredProjectId ? `?preferred_project_id=${encodeURIComponent(preferredProjectId)}` : "";
+    return this.request("GET", `/cards/resolve/${shortId}${qs}`);
+  }
   async bulkGetCards(projectId, shortIds) {
     return this.request("POST", `/projects/${projectId}/cards/bulk-get`, {
       shortIds
@@ -2476,6 +2498,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 +2636,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(() => {});
     }
   }
@@ -5731,9 +5762,51 @@ async function handleToolCall(name, args, deps) {
       }
       if (hasShortId) {
         const shortId = z.number().int().positive().parse(args.shortId);
-        const projectId = args.projectId || getProjectId();
-        const result2 = await client3.getCardByShortId(projectId, shortId);
-        return { success: true, ...result2 };
+        const explicitProjectId = args.projectId;
+        if (explicitProjectId) {
+          const result2 = await client3.getCardByShortId(explicitProjectId, shortId);
+          return { success: true, ...result2 };
+        }
+        const activeProjectId = deps.getActiveProjectId();
+        const resolved = await client3.resolveCardByShortId(shortId, activeProjectId);
+        if (resolved.kind === "found") {
+          const cardTitle = resolved.card?.title ?? `#${shortId}`;
+          const where = resolved.project.workspaceName ? `project "${resolved.project.name ?? resolved.project.id}" (workspace "${resolved.project.workspaceName}")` : `project "${resolved.project.name ?? resolved.project.id}"`;
+          const established = activeProjectId == null;
+          if (established) {
+            deps.setActiveProject(resolved.project.id);
+          }
+          return {
+            success: true,
+            card: resolved.card,
+            resolvedProject: resolved.project,
+            activeProjectId: resolved.project.id,
+            note: established ? `Resolved #${shortId} → "${cardTitle}" in ${where}. No active project was set — set to this for follow-up references.` : `Resolved #${shortId} → "${cardTitle}" in ${where} (your active project).`
+          };
+        }
+        if (resolved.kind === "not_in_preferred") {
+          const list = resolved.candidates.map((c) => `  • "${c.title}" — project "${c.projectName ?? c.projectId}"${c.workspaceName ? ` / workspace "${c.workspaceName}"` : ""} (projectId: ${c.projectId})`).join(`
+`);
+          throw new Error(`#${shortId} is not in your active project (projectId: ${resolved.preferredProjectId}). ` + `It exists in ${resolved.candidates.length} other project(s) you can access:
+${list}
+
+` + `Switch with harmony_set_project_context, or pass an explicit projectId to fetch it directly.`);
+        }
+        if (resolved.kind === "ambiguous") {
+          const list = resolved.candidates.map((c) => `  • "${c.title}" — project "${c.projectName ?? c.projectId}"${c.workspaceName ? ` / workspace "${c.workspaceName}"` : ""} (projectId: ${c.projectId})`).join(`
+`);
+          return {
+            success: true,
+            needsDisambiguation: true,
+            shortId,
+            candidates: resolved.candidates,
+            message: `#${shortId} exists in ${resolved.candidates.length} projects you can access:
+${list}
+
+` + `Ask which one is meant, then re-fetch with an explicit projectId ` + `(or call harmony_set_project_context first).`
+          };
+        }
+        throw new Error(resolved.searchedProjectCount === 0 ? `#${shortId} can't be resolved: no project is accessible to this connection. ` + `Check the workspace this connection is authorized for with harmony_list_workspaces.` : `Card #${shortId} was not found in any of the ${resolved.searchedProjectCount} ` + `project(s) across ${resolved.searchedWorkspaceCount} workspace(s) this connection can access. ` + `Use harmony_list_projects to see them, or pass an explicit projectId.`);
       }
       const cardId = z.string().uuid().parse(args.cardId);
       const result = await client3.getCard(cardId);
@@ -6143,6 +6216,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`);
   }
@@ -1298,6 +1316,10 @@ class HarmonyApiClient {
   async getCardByShortId(projectId, shortId) {
     return this.request("GET", `/projects/${projectId}/cards/${shortId}`);
   }
+  async resolveCardByShortId(shortId, preferredProjectId) {
+    const qs = preferredProjectId ? `?preferred_project_id=${encodeURIComponent(preferredProjectId)}` : "";
+    return this.request("GET", `/cards/resolve/${shortId}${qs}`);
+  }
   async bulkGetCards(projectId, shortIds) {
     return this.request("POST", `/projects/${projectId}/cards/bulk-get`, {
       shortIds

package/package.json

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

package/src/api-client.ts

@@ -164,6 +164,46 @@ export interface CardExternalLinkRow {
   created_at: string;
 }
 
+/** One candidate card returned by the cross-project short-id resolver (#709). */
+export interface ResolveCardCandidate {
+  cardId: string;
+  title: string;
+  projectId: string;
+  projectName: string | null;
+  workspaceId: string;
+  workspaceName: string | null;
+}
+
+/** Discriminated result of GET /cards/resolve/:shortId (#709). `found` carries
+ * the hydrated card + its project (for sticky-context + confirm-back);
+ * `ambiguous` carries the candidates so the caller asks which one; `not_found`
+ * carries the searched scope for a legible failure; `not_in_preferred` (#428)
+ * means a deliberately-set active project (the hard scope) doesn't hold the id,
+ * and carries the projects that DO so the caller can switch or pass an explicit
+ * projectId — the tool never silently hops to another project. */
+export type ResolveCardApiResult =
+  | {
+      kind: "found";
+      card: unknown;
+      project: {
+        id: string;
+        name: string | null;
+        workspaceId: string;
+        workspaceName: string | null;
+      };
+    }
+  | { kind: "ambiguous"; candidates: ResolveCardCandidate[] }
+  | {
+      kind: "not_found";
+      searchedWorkspaceCount: number;
+      searchedProjectCount: number;
+    }
+  | {
+      kind: "not_in_preferred";
+      preferredProjectId: string;
+      candidates: ResolveCardCandidate[];
+    };
+
 /** Result of the classify-card classifier (card #415). Any field may be null
  * if the LLM didn't return a usable value. `model_override` is never touched. */
 export interface CardClassificationResult {
@@ -461,6 +501,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[] }> {
@@ -678,6 +734,21 @@ export class HarmonyApiClient {
     return this.request("GET", `/projects/${projectId}/cards/${shortId}`);
   }
 
+  // #709: resolve a `#shortId` across every project the caller can reach when no
+  // explicit project is in play (the remote/OAuth MCP seeds a workspace but no
+  // project). `preferredProjectId` biases to the session's active/sticky project
+  // so a deliberately-set context wins outright instead of reading as ambiguous.
+  // Always resolves (HTTP 200) with a discriminated body — the caller decides.
+  async resolveCardByShortId(
+    shortId: number,
+    preferredProjectId?: string | null,
+  ): Promise<ResolveCardApiResult> {
+    const qs = preferredProjectId
+      ? `?preferred_project_id=${encodeURIComponent(preferredProjectId)}`
+      : "";
+    return this.request("GET", `/cards/resolve/${shortId}${qs}`);
+  }
+
   async bulkGetCards(
     projectId: string,
     shortIds: number[],
@@ -1067,6 +1138,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 +1152,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

@@ -2872,9 +2872,113 @@ async function handleToolCall(
       }
       if (hasShortId) {
         const shortId = z.number().int().positive().parse(args.shortId);
-        const projectId = (args.projectId as string) || getProjectId();
-        const result = await client.getCardByShortId(projectId, shortId);
-        return { success: true, ...result };
+        const explicitProjectId = args.projectId as string | undefined;
+
+        // Explicit projectId is the deterministic override: fetch from exactly
+        // that project and error if it's not there — never look elsewhere.
+        if (explicitProjectId) {
+          const result = await client.getCardByShortId(
+            explicitProjectId,
+            shortId,
+          );
+          return { success: true, ...result };
+        }
+
+        // No explicit project: resolve the `#shortId` (#709). The active/sticky
+        // project is a HARD SCOPE (#428) — when one is set, the resolver only
+        // matches within it (a miss comes back as `not_in_preferred`, handled
+        // below) and this read never repoints it. Cross-project auto-resolution
+        // + sticky happens ONLY when no active project is set — the remote/OAuth
+        // MCP case this feature exists for, where the session seeds a workspace
+        // but no project.
+        const activeProjectId = deps.getActiveProjectId();
+        const resolved = await client.resolveCardByShortId(
+          shortId,
+          activeProjectId,
+        );
+
+        if (resolved.kind === "found") {
+          const cardTitle =
+            (resolved.card as { title?: string } | null)?.title ??
+            `#${shortId}`;
+          const where = resolved.project.workspaceName
+            ? `project "${resolved.project.name ?? resolved.project.id}" (workspace "${resolved.project.workspaceName}")`
+            : `project "${resolved.project.name ?? resolved.project.id}"`;
+          // Sticky ONLY when this ESTABLISHES a context (none was set). A
+          // deliberately-set active project is a hard scope: `found` there means
+          // the card was already in it, so there is nothing to change — and we
+          // never let a read silently repoint a context the user chose (which,
+          // on the local stdio MCP, persists to ~/.harmony-mcp/config.json
+          // across sessions). Confirm the target back either way so a
+          // wrong-context resolve is visible immediately.
+          const established = activeProjectId == null;
+          if (established) {
+            deps.setActiveProject(resolved.project.id);
+          }
+          return {
+            success: true,
+            card: resolved.card,
+            resolvedProject: resolved.project,
+            activeProjectId: resolved.project.id,
+            note: established
+              ? `Resolved #${shortId} → "${cardTitle}" in ${where}. No active project was set — set to this for follow-up references.`
+              : `Resolved #${shortId} → "${cardTitle}" in ${where} (your active project).`,
+          };
+        }
+
+        if (resolved.kind === "not_in_preferred") {
+          // Hard scope (#428): the active project is a constraint the user set,
+          // so a `#shortId` that isn't in it is an error — NOT a silent hop to
+          // whatever other project happens to carry that number, and NOT a
+          // change to the active project. Name where it *does* live so the
+          // caller can switch context or fetch it explicitly.
+          const list = resolved.candidates
+            .map(
+              (c) =>
+                `  • "${c.title}" — project "${c.projectName ?? c.projectId}"${
+                  c.workspaceName ? ` / workspace "${c.workspaceName}"` : ""
+                } (projectId: ${c.projectId})`,
+            )
+            .join("\n");
+          throw new Error(
+            `#${shortId} is not in your active project (projectId: ${resolved.preferredProjectId}). ` +
+              `It exists in ${resolved.candidates.length} other project(s) you can access:\n${list}\n\n` +
+              `Switch with harmony_set_project_context, or pass an explicit projectId to fetch it directly.`,
+          );
+        }
+
+        if (resolved.kind === "ambiguous") {
+          // Never guess: hand the candidates back so the caller can disambiguate.
+          const list = resolved.candidates
+            .map(
+              (c) =>
+                `  • "${c.title}" — project "${c.projectName ?? c.projectId}"${
+                  c.workspaceName ? ` / workspace "${c.workspaceName}"` : ""
+                } (projectId: ${c.projectId})`,
+            )
+            .join("\n");
+          return {
+            success: true,
+            needsDisambiguation: true,
+            shortId,
+            candidates: resolved.candidates,
+            message:
+              `#${shortId} exists in ${resolved.candidates.length} projects you can access:\n${list}\n\n` +
+              `Ask which one is meant, then re-fetch with an explicit projectId ` +
+              `(or call harmony_set_project_context first).`,
+          };
+        }
+
+        // not_found — name the searched scope instead of the bare "No project
+        // specified", and point at the tools that list the caller's options.
+        throw new Error(
+          resolved.searchedProjectCount === 0
+            ? `#${shortId} can't be resolved: no project is accessible to this connection. ` +
+                `Check the workspace this connection is authorized for with harmony_list_workspaces.`
+            : `Card #${shortId} was not found in any of the ${resolved.searchedProjectCount} ` +
+                `project(s) across ${resolved.searchedWorkspaceCount} workspace(s) this connection can access. ` +
+                `Use harmony_list_projects to see them, or pass an explicit projectId.`,
+        );
       }
       const cardId = z.string().uuid().parse(args.cardId);
       const result = await client.getCard(cardId);
@@ -3489,6 +3593,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 };
     }