@gethmy/mcp 2.17.1 → 2.19.0

package/dist/cli.js

@@ -1869,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
@@ -5763,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);
@@ -7215,7 +7261,7 @@ import {
 } from "node:fs";
 import { homedir as homedir6 } from "node:os";
 import { dirname as dirname3, join as join8 } from "node:path";
-import * as p3 from "@clack/prompts";
+import * as p4 from "@clack/prompts";
 init_config();
 init_oauth_login();
 
@@ -7273,10 +7319,21 @@ function detectAgents(cwd = process.cwd()) {
   });
 }
 
+// src/tui/confirm.ts
+import * as p from "@clack/prompts";
+function shouldAssumeYes(yesFlag, isTTY) {
+  return yesFlag === true || isTTY !== true;
+}
+async function confirmOrDefault(assumeYes, opts) {
+  if (assumeYes)
+    return opts.initialValue ?? true;
+  return p.confirm(opts);
+}
+
 // src/tui/docs.ts
 import { existsSync as existsSync6, readdirSync as readdirSync2, readFileSync as readFileSync5, statSync as statSync2 } from "node:fs";
 import { isAbsolute, join as join7, resolve, sep as sep2 } from "node:path";
-import * as p from "@clack/prompts";
+import * as p2 from "@clack/prompts";
 
 // src/tui/theme.ts
 import pc from "picocolors";
@@ -7924,11 +7981,11 @@ async function runDocsStep(cwd) {
   const info = scanProject(cwd);
   const hasDocs = info.existingDocs.agentsMd || info.existingDocs.claudeMd;
   if (!hasDocs) {
-    const shouldGenerate = await p.confirm({
+    const shouldGenerate = await p2.confirm({
       message: "No project docs found. Generate AGENTS.md and CLAUDE.md?",
       initialValue: true
     });
-    if (p.isCancel(shouldGenerate) || !shouldGenerate) {
+    if (p2.isCancel(shouldGenerate) || !shouldGenerate) {
       return { files: [], issues: [], skipped: true };
     }
     const files = [];
@@ -7949,32 +8006,32 @@ async function runDocsStep(cwd) {
         type: "text"
       });
     }
-    p.log.success(`Generated ${files.length} doc file(s): ${files.map((f) => f.path.replace(cwd + "/", "")).join(", ")}`);
+    p2.log.success(`Generated ${files.length} doc file(s): ${files.map((f) => f.path.replace(cwd + "/", "")).join(", ")}`);
     return { files, issues: [], skipped: false };
   }
-  const shouldVerify = await p.confirm({
+  const shouldVerify = await p2.confirm({
     message: "Project docs found. Verify for issues?",
     initialValue: false
   });
-  if (p.isCancel(shouldVerify) || !shouldVerify) {
+  if (p2.isCancel(shouldVerify) || !shouldVerify) {
     return { files: [], issues: [], skipped: true };
   }
   const issues = verifyDocs(cwd);
   if (issues.length === 0) {
-    p.log.success("No issues found in project docs.");
+    p2.log.success("No issues found in project docs.");
   } else {
     for (const issue of issues) {
       const prefix = `${colors.bold(issue.file)}:`;
       if (issue.severity === "error") {
-        p.log.error(`${prefix} ${issue.message}`);
+        p2.log.error(`${prefix} ${issue.message}`);
       } else {
-        p.log.warning(`${prefix} ${issue.message}`);
+        p2.log.warning(`${prefix} ${issue.message}`);
       }
       if (issue.fix) {
-        p.log.message(`  ${symbols.arrow} ${colors.dim(issue.fix)}`);
+        p2.log.message(`  ${symbols.arrow} ${colors.dim(issue.fix)}`);
       }
     }
-    p.log.info(`Found ${issues.length} issue(s) (${issues.filter((i) => i.severity === "error").length} errors, ${issues.filter((i) => i.severity === "warning").length} warnings)`);
+    p2.log.info(`Found ${issues.length} issue(s) (${issues.filter((i) => i.severity === "error").length} errors, ${issues.filter((i) => i.severity === "warning").length} warnings)`);
   }
   return { files: [], issues, skipped: false };
 }
@@ -7989,7 +8046,7 @@ import {
 } from "node:fs";
 import { homedir as homedir5 } from "node:os";
 import { dirname as dirname2 } from "node:path";
-import * as p2 from "@clack/prompts";
+import * as p3 from "@clack/prompts";
 function ensureDir(dirPath) {
   if (!existsSync7(dirPath)) {
     mkdirSync4(dirPath, { recursive: true, mode: 493 });
@@ -8109,7 +8166,7 @@ function appendToToml(filePath, section, content, options = {}) {
 async function writeFilesWithProgress(files, options = {}) {
   const results = [];
   const home = homedir5();
-  const spinner2 = p2.spinner();
+  const spinner2 = p3.spinner();
   spinner2.start("Writing configuration files...");
   for (const file of files) {
     let result;
@@ -8601,6 +8658,10 @@ async function runSetup(options = {}) {
   const home = homedir6();
   console.clear();
   console.log(messages.header());
+  const assumeYes = shouldAssumeYes(options.yes, process.stdin.isTTY);
+  if (assumeYes) {
+    p4.log.info(options.yes ? "Non-interactive mode (--yes): using the default answer for each confirmation." : "No interactive terminal detected: using the default answer for each confirmation.");
+  }
   const existingConfig = loadConfig();
   const alreadyConfigured = isConfigured();
   const skillsStatus = areSkillsInstalled(cwd);
@@ -8620,7 +8681,7 @@ async function runSetup(options = {}) {
   let createdNewAccount = false;
   let oauthTokens;
   if (options.apiKey) {
-    p3.log.warn(colors.warning(`--api-key is deprecated and insecure: the key is exposed in your shell
+    p4.log.warn(colors.warning(`--api-key is deprecated and insecure: the key is exposed in your shell
 history, terminal scrollback, and the process list. Prefer the browser
 sign-in (run \`npx @gethmy/mcp setup\` with no --api-key). Use --api-key
 only for unattended CI where you accept that risk.`));
@@ -8631,7 +8692,7 @@ only for unattended CI where you accept that risk.`));
     if (!useNewAccount && options.apiKey) {
       useNewAccount = false;
     } else if (!useNewAccount && !options.apiKey) {
-      const getStarted = await p3.select({
+      const getStarted = await p4.select({
         message: "How would you like to connect?",
         options: [
           {
@@ -8652,15 +8713,15 @@ only for unattended CI where you accept that risk.`));
         ],
         initialValue: "browser"
       });
-      if (p3.isCancel(getStarted)) {
-        p3.cancel("Setup cancelled");
+      if (p4.isCancel(getStarted)) {
+        p4.cancel("Setup cancelled");
         process.exit(0);
       }
       useNewAccount = getStarted === "create";
       useBrowserAuth = getStarted === "browser";
     }
     if (useBrowserAuth) {
-      const spinner4 = p3.spinner();
+      const spinner4 = p4.spinner();
       spinner4.start("Opening your browser to authorize…");
       try {
         oauthTokens = await loginWithBrowser({
@@ -8685,12 +8746,12 @@ ${colors.dim(url)}`);
       } catch (error) {
         spinner4.stop(colors.error("Browser authorization failed"));
         const msg = error instanceof Error ? error.message : "Unknown error";
-        p3.log.error(msg);
-        p3.log.info("You can retry, or run with --api-key for unattended setup.");
+        p4.log.error(msg);
+        p4.log.info("You can retry, or run with --api-key for unattended setup.");
         process.exit(1);
       }
     } else if (useNewAccount) {
-      const fullName = options.name || await p3.text({
+      const fullName = options.name || await p4.text({
         message: "Full name",
         placeholder: "Jane Smith",
         validate: (v) => {
@@ -8701,11 +8762,11 @@ ${colors.dim(url)}`);
           return;
         }
       });
-      if (p3.isCancel(fullName)) {
-        p3.cancel("Setup cancelled");
+      if (p4.isCancel(fullName)) {
+        p4.cancel("Setup cancelled");
         process.exit(0);
       }
-      const email = options.userEmail || await p3.text({
+      const email = options.userEmail || await p4.text({
         message: "Email",
         placeholder: "you@example.com",
         validate: (v) => {
@@ -8718,11 +8779,11 @@ ${colors.dim(url)}`);
           return;
         }
       });
-      if (p3.isCancel(email)) {
-        p3.cancel("Setup cancelled");
+      if (p4.isCancel(email)) {
+        p4.cancel("Setup cancelled");
         process.exit(0);
       }
-      const password2 = await p3.password({
+      const password2 = await p4.password({
         message: "Password",
         validate: (v) => {
           if (!v)
@@ -8734,11 +8795,11 @@ ${colors.dim(url)}`);
           return;
         }
       });
-      if (p3.isCancel(password2)) {
-        p3.cancel("Setup cancelled");
+      if (p4.isCancel(password2)) {
+        p4.cancel("Setup cancelled");
         process.exit(0);
       }
-      const spinner4 = p3.spinner();
+      const spinner4 = p4.spinner();
       spinner4.start("Creating your account...");
       try {
         const result = await onboardNewUser({
@@ -8758,15 +8819,15 @@ ${colors.dim(url)}`);
         saveConfig({ apiKey, userEmail, apiUrl: API_URL });
         setActiveWorkspace(selectedWorkspaceIdFromSignup);
         setActiveProject(selectedProjectIdFromSignup);
-        p3.log.success("Workspace and board created");
+        p4.log.success("Workspace and board created");
       } catch (error) {
         spinner4.stop(colors.error("Account creation failed"));
         const msg = error instanceof Error ? error.message : "Unknown error";
         if (msg.includes("already") || msg.includes("409")) {
-          p3.log.error("Account already exists. Sign in at app.gethmy.com to get your API key, or re-run setup and choose 'I already have an API key'.");
+          p4.log.error("Account already exists. Sign in at app.gethmy.com to get your API key, or re-run setup and choose 'I already have an API key'.");
         } else {
-          p3.log.error(msg);
-          p3.log.info("Please try again or visit https://app.gethmy.com");
+          p4.log.error(msg);
+          p4.log.info("Please try again or visit https://app.gethmy.com");
         }
         process.exit(1);
       }
@@ -8774,7 +8835,7 @@ ${colors.dim(url)}`);
       apiKey = options.apiKey;
       needsApiKey = true;
     } else {
-      const keyInput = await p3.text({
+      const keyInput = await p4.text({
         message: "Enter your Harmony API key",
         placeholder: "hmy_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
         validate: (value) => {
@@ -8787,24 +8848,24 @@ ${colors.dim(url)}`);
           return;
         }
       });
-      if (p3.isCancel(keyInput)) {
-        p3.cancel("Setup cancelled");
+      if (p4.isCancel(keyInput)) {
+        p4.cancel("Setup cancelled");
         process.exit(0);
       }
       apiKey = keyInput;
       needsApiKey = true;
     }
   } else {
-    p3.log.success(`Using existing API key: ${apiKey.slice(0, 8)}...`);
+    p4.log.success(`Using existing API key: ${apiKey.slice(0, 8)}...`);
   }
-  const spinner3 = p3.spinner();
+  const spinner3 = p4.spinner();
   if (!createdNewAccount) {
     spinner3.start("Validating API key...");
     const validation = await validateApiKey(apiKey);
     if (!validation.valid) {
       spinner3.stop(colors.error("API key validation failed"));
-      p3.log.error(validation.error || "Could not connect to Harmony API");
-      p3.log.info("Get an API key at: https://app.gethmy.com/user/keys");
+      p4.log.error(validation.error || "Could not connect to Harmony API");
+      p4.log.info("Get an API key at: https://app.gethmy.com/user/keys");
       process.exit(1);
     }
     if (!userEmail) {
@@ -8815,13 +8876,13 @@ ${colors.dim(url)}`);
   let selectedAgents = [];
   let installMode = options.installMode || "global";
   if (skillsStatus.installed && !options.force) {
-    p3.log.success(`Skills already installed (${skillsStatus.location})`);
-    const reinstall = await p3.confirm({
+    p4.log.success(`Skills already installed (${skillsStatus.location})`);
+    const reinstall = await confirmOrDefault(assumeYes, {
       message: "Reinstall skills?",
       initialValue: false
     });
-    if (p3.isCancel(reinstall)) {
-      p3.cancel("Setup cancelled");
+    if (p4.isCancel(reinstall)) {
+      p4.cancel("Setup cancelled");
       process.exit(0);
     }
     needsSkills = reinstall;
@@ -8836,23 +8897,23 @@ ${colors.dim(url)}`);
         label: agent.name,
         hint: agent.detected ? colors.success(`${agent.description} (detected)`) : colors.dim(`${agent.description}`)
       }));
-      const agentSelection = await p3.multiselect({
+      const agentSelection = await p4.multiselect({
         message: "Select agents to configure",
         options: agentOptions,
         initialValues: detectedAgents2.filter((a) => a.detected).map((a) => a.id),
         required: true
       });
-      if (p3.isCancel(agentSelection)) {
-        p3.cancel("Setup cancelled");
+      if (p4.isCancel(agentSelection)) {
+        p4.cancel("Setup cancelled");
         process.exit(0);
       }
       selectedAgents = agentSelection;
     }
     if (selectedAgents.length === 0) {
-      p3.log.warning("No agents selected. Skipping skills installation.");
+      p4.log.warning("No agents selected. Skipping skills installation.");
       needsSkills = false;
     } else if (!options.installMode) {
-      const modeSelection = await p3.select({
+      const modeSelection = await p4.select({
         message: "Where should Harmony skills be installed?",
         options: [
           {
@@ -8868,8 +8929,8 @@ ${colors.dim(url)}`);
         ],
         initialValue: "global"
       });
-      if (p3.isCancel(modeSelection)) {
-        p3.cancel("Setup cancelled");
+      if (p4.isCancel(modeSelection)) {
+        p4.cancel("Setup cancelled");
         process.exit(0);
       }
       installMode = modeSelection;
@@ -8893,7 +8954,7 @@ ${colors.dim(url)}`);
         spinner3.stop(colors.warning(`Slug "${options.projectSlug}" is ambiguous — it exists in multiple workspaces`));
         const list = resolved.candidates.map((c) => `  • ${c.workspaceName ?? c.workspaceId}`).join(`
 `);
-        p3.log.warning(`"${options.projectSlug}" matches projects in multiple workspaces:
+        p4.log.warning(`"${options.projectSlug}" matches projects in multiple workspaces:
 ${list}
 Specify the workspace with --workspace <id>, or select one below.`);
       } else {
@@ -8914,7 +8975,7 @@ Specify the workspace with --workspace <id>, or select one below.`);
       spinner3.stop(colors.success(`Found ${workspaces.length} workspace(s)`));
     } catch (_error) {
       spinner3.stop(colors.warning("Could not fetch workspaces"));
-      p3.log.warning("Skipping workspace/project selection. You can set this later.");
+      p4.log.warning("Skipping workspace/project selection. You can set this later.");
       needsContext = false;
     }
     if (needsContext && workspaces.length > 0) {
@@ -8926,12 +8987,12 @@ Specify the workspace with --workspace <id>, or select one below.`);
           value: ws.id,
           label: ws.name
         }));
-        const workspaceSelection = await p3.select({
+        const workspaceSelection = await p4.select({
           message: candidateIds.size > 0 ? `Select workspace for "${options.projectSlug}"` : "Select workspace",
           options: workspaceOptions
         });
-        if (p3.isCancel(workspaceSelection)) {
-          p3.cancel("Setup cancelled");
+        if (p4.isCancel(workspaceSelection)) {
+          p4.cancel("Setup cancelled");
           process.exit(0);
         }
         selectedWorkspaceId = workspaceSelection;
@@ -8950,7 +9011,7 @@ Specify the workspace with --workspace <id>, or select one below.`);
         spinner3.stop(colors.success(`Found ${projects.length} project(s)`));
       } catch (_error) {
         spinner3.stop(colors.warning("Could not fetch projects"));
-        p3.log.warning("Skipping project selection. You can set this later.");
+        p4.log.warning("Skipping project selection. You can set this later.");
       }
       if (projects.length > 0 && !selectedProjectId) {
         const projectOptions = projects.map((proj) => ({
@@ -8958,18 +9019,18 @@ Specify the workspace with --workspace <id>, or select one below.`);
           label: proj.name,
           hint: proj.description ? colors.dim(proj.description.slice(0, 50)) : undefined
         }));
-        const projectSelection = await p3.select({
+        const projectSelection = await p4.select({
           message: "Select project",
           options: projectOptions
         });
-        if (p3.isCancel(projectSelection)) {
-          p3.cancel("Setup cancelled");
+        if (p4.isCancel(projectSelection)) {
+          p4.cancel("Setup cancelled");
           process.exit(0);
         }
         selectedProjectId = projectSelection;
-        selectedProjectName = projects.find((p4) => p4.id === selectedProjectId)?.name;
+        selectedProjectName = projects.find((p5) => p5.id === selectedProjectId)?.name;
       } else if (selectedProjectId && !selectedProjectName) {
-        selectedProjectName = projects.find((p4) => p4.id === selectedProjectId)?.name;
+        selectedProjectName = projects.find((p5) => p5.id === selectedProjectId)?.name;
       }
     }
   }
@@ -9016,7 +9077,7 @@ Specify the workspace with --workspace <id>, or select one below.`);
   }
   const detectedAgents = detectAgents(cwd);
   console.log("");
-  p3.log.step("Summary");
+  p4.log.step("Summary");
   console.log("");
   if (oauthTokens) {
     console.log(`  ${colors.bold("Credential:")} Browser sign-in (OAuth, workspace-scoped)`);
@@ -9072,12 +9133,12 @@ Specify the workspace with --workspace <id>, or select one below.`);
     }
   }
   console.log("");
-  const shouldProceed = await p3.confirm({
+  const shouldProceed = await confirmOrDefault(assumeYes, {
     message: "Proceed with setup?",
     initialValue: true
   });
-  if (p3.isCancel(shouldProceed) || !shouldProceed) {
-    p3.cancel("Setup cancelled");
+  if (p4.isCancel(shouldProceed) || !shouldProceed) {
+    p4.cancel("Setup cancelled");
     process.exit(0);
   }
   console.log("");
@@ -9107,7 +9168,7 @@ Specify the workspace with --workspace <id>, or select one below.`);
         }
         symlinkSync(symlink.target, symlink.link);
       } catch {
-        p3.log.warning(`Failed to create symlink: ${symlink.link}`);
+        p4.log.warning(`Failed to create symlink: ${symlink.link}`);
       }
     }
   }
@@ -9121,16 +9182,19 @@ Specify the workspace with --workspace <id>, or select one below.`);
         await writeMcpConfigFallback(home);
         console.log(`  ${colors.success("✓")} ${colors.dim(formatPath(join8(home, ".claude", "settings.json"), home))} ${colors.dim("(updated)")}`);
       } catch {
-        p3.log.warning("Could not register MCP server. Run manually: claude mcp add --transport stdio harmony -- npx -y @gethmy/mcp@latest serve");
+        p4.log.warning("Could not register MCP server. Run manually: claude mcp add --transport stdio harmony -- npx -y @gethmy/mcp@latest serve");
       }
     }
   }
   if (claudeDetected || selectedAgents.includes("claude")) {
     const allowAll = options.allowAllTools === true;
     const message = allowAll ? "Allowlist EVERY Harmony tool without confirmation, including destructive ones (delete/archive/api-key/invite)?" : "Allowlist common Harmony tools (reads + create/update/move/comment) so /hmy doesn't prompt each time? Destructive tools (delete/archive/api-key/invite) will still ask.";
-    const allowTools = await p3.confirm({ message, initialValue: true });
-    if (p3.isCancel(allowTools)) {
-      p3.cancel("Setup cancelled.");
+    const allowTools = await confirmOrDefault(assumeYes, {
+      message,
+      initialValue: true
+    });
+    if (p4.isCancel(allowTools)) {
+      p4.cancel("Setup cancelled.");
       process.exit(0);
     }
     if (allowTools) {
@@ -9139,7 +9203,7 @@ Specify the workspace with --workspace <id>, or select one below.`);
         const scope = allowAll ? "all tools" : "safe tools";
         console.log(`  ${colors.success("✓")} ${colors.dim(formatPath(join8(home, ".claude", "settings.json"), home))} ${colors.dim(result === "added" ? `(${scope} allowlisted)` : `(${scope} already allowlisted)`)}`);
       } catch {
-        p3.log.warning("Could not allowlist Harmony tools. Run /permissions in Claude Code and choose “always allow” for Harmony, or add mcp__harmony to permissions.allow in ~/.claude/settings.json.");
+        p4.log.warning("Could not allowlist Harmony tools. Run /permissions in Claude Code and choose “always allow” for Harmony, or add mcp__harmony to permissions.allow in ~/.claude/settings.json.");
       }
     } else {
       console.log(`  ${colors.dim("Skipped tool allowlist — you'll be prompted per tool, or run /permissions in Claude Code later.")}`);
@@ -9159,7 +9223,7 @@ Specify the workspace with --workspace <id>, or select one below.`);
       setActiveProject(selectedProjectId);
   }
   console.log("");
-  p3.outro(colors.success("Setup complete!"));
+  p4.outro(colors.success("Setup complete!"));
   if (createdNewAccount && selectedWorkspaceNameFromSignup) {
     const wsSlug = selectedWorkspaceNameFromSignup.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
     const projSlug = (selectedProjectNameFromSignup || "my-first-board").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
@@ -9292,7 +9356,7 @@ program.command("reset").description("Remove stored configuration").action(() =>
   console.log(`
 To reconfigure, run: npx @gethmy/mcp setup`);
 });
-program.command("setup").description("Smart setup wizard for Harmony MCP (recommended)").argument("[slug]", "Project slug — resolves to workspace + project in one step (e.g. harmony-6590761b)").option("-f, --force", "Overwrite existing configuration files").option("-k, --api-key <key>", "DEPRECATED (insecure: key leaks via argv/shell history). For unattended CI only — interactive setup uses browser sign-in.").option("-e, --email <email>", "Your email for auto-assignment").option("-a, --agents <agents...>", "Agents to configure: claude, codex, cursor, windsurf").option("-l, --local", "Install skills locally in project directory").option("-g, --global", "Install skills globally (recommended)").option("-w, --workspace <id>", "Set workspace context (UUID)").option("-p, --project <id>", "Set project context (UUID)").option("--skip-context", "Skip workspace/project selection").option("--skip-docs", "Skip project docs scaffold/verification").option("--new", "Create a new account (skip the choice prompt)").option("-n, --name <name>", "Full name (for account creation)").option("--allow-all-tools", "Allowlist every Harmony tool (incl. destructive: delete/archive/api-key/invite) without confirmation. Default allowlists only read + routine-write tools; destructive tools keep prompting.").action(async (slug, options) => {
+program.command("setup").description("Smart setup wizard for Harmony MCP (recommended)").argument("[slug]", "Project slug — resolves to workspace + project in one step (e.g. harmony-6590761b)").option("-f, --force", "Overwrite existing configuration files").option("-k, --api-key <key>", "DEPRECATED (insecure: key leaks via argv/shell history). For unattended CI only — interactive setup uses browser sign-in.").option("-e, --email <email>", "Your email for auto-assignment").option("-a, --agents <agents...>", "Agents to configure: claude, codex, cursor, windsurf").option("-l, --local", "Install skills locally in project directory").option("-g, --global", "Install skills globally (recommended)").option("-w, --workspace <id>", "Set workspace context (UUID)").option("-p, --project <id>", "Set project context (UUID)").option("--skip-context", "Skip workspace/project selection").option("--skip-docs", "Skip project docs scaffold/verification").option("-y, --yes", "Non-interactive: answer every yes/no confirmation with its default. Implied when there is no TTY (pipe / coding agent / CI). Provide the other inputs via flags (--api-key, --agents, --workspace/--project or --skip-context, --skip-docs).").option("--new", "Create a new account (skip the choice prompt)").option("-n, --name <name>", "Full name (for account creation)").option("--allow-all-tools", "Allowlist every Harmony tool (incl. destructive: delete/archive/api-key/invite) without confirmation. Default allowlists only read + routine-write tools; destructive tools keep prompting.").action(async (slug, options) => {
   await runSetup({
     force: options.force,
     apiKey: options.apiKey,
@@ -9306,7 +9370,8 @@ program.command("setup").description("Smart setup wizard for Harmony MCP (recomm
     skipDocs: options.skipDocs,
     newAccount: options.new,
     name: options.name,
-    allowAllTools: options.allowAllTools
+    allowAllTools: options.allowAllTools,
+    yes: options.yes
   });
 });
 program.parse();

package/dist/index.js

@@ -1864,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
@@ -5758,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);

package/dist/lib/api-client.js

@@ -1316,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.1",
+  "version": "2.19.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",
+    "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: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

@@ -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 {
@@ -694,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[],

package/src/cli.ts

@@ -167,6 +167,10 @@ program
   .option("-p, --project <id>", "Set project context (UUID)")
   .option("--skip-context", "Skip workspace/project selection")
   .option("--skip-docs", "Skip project docs scaffold/verification")
+  .option(
+    "-y, --yes",
+    "Non-interactive: answer every yes/no confirmation with its default. Implied when there is no TTY (pipe / coding agent / CI). Provide the other inputs via flags (--api-key, --agents, --workspace/--project or --skip-context, --skip-docs).",
+  )
   .option("--new", "Create a new account (skip the choice prompt)")
   .option("-n, --name <name>", "Full name (for account creation)")
   .option(
@@ -192,6 +196,7 @@ program
       newAccount: options.new,
       name: options.name,
       allowAllTools: options.allowAllTools,
+      yes: options.yes,
     });
   });
 

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);

package/src/tui/confirm.ts

@@ -0,0 +1,33 @@
+import * as p from "@clack/prompts";
+
+/**
+ * Whether yes/no confirmations should resolve to their default without
+ * prompting. True when the user passed `--yes`, OR when there is no interactive
+ * terminal on stdin (a pipe, a file, or nothing — how a coding agent or CI runs
+ * commands). In that second case `@clack/prompts` can't read a keypress and the
+ * confirm would otherwise stall or cancel the whole run, so we take the default.
+ *
+ * `isTTY` is `process.stdin.isTTY`, which Node sets to `true` only for a real
+ * TTY and leaves `undefined` otherwise — hence the `!== true` test.
+ */
+export function shouldAssumeYes(
+  yesFlag: boolean | undefined,
+  isTTY: boolean | undefined,
+): boolean {
+  return yesFlag === true || isTTY !== true;
+}
+
+/**
+ * Resolve a confirmation. In non-interactive mode (see {@link shouldAssumeYes})
+ * it returns the prompt's documented default (`initialValue`, or `true` when
+ * unset) instead of blocking on a keypress that will never arrive. Interactive
+ * runs (a human at a TTY, no `--yes`) delegate to `p.confirm` and behave exactly
+ * as before, including returning the cancel symbol on Ctrl-C.
+ */
+export async function confirmOrDefault(
+  assumeYes: boolean,
+  opts: { message: string; initialValue?: boolean },
+): Promise<boolean | symbol> {
+  if (assumeYes) return opts.initialValue ?? true;
+  return p.confirm(opts);
+}

package/src/tui/setup.ts

@@ -26,6 +26,7 @@ import { loginWithBrowser, type OAuthTokens } from "../oauth-login.js";
 import { onboardNewUser } from "../onboard.js";
 import { buildSkillFile, HARMONY_WORKFLOW_PROMPT } from "../skills.js";
 import { type AgentId, detectAgents } from "./agents.js";
+import { confirmOrDefault, shouldAssumeYes } from "./confirm.js";
 import { runDocsStep } from "./docs.js";
 import { colors, formatPath, messages } from "./theme.js";
 import { getWriteSummary, writeFilesWithProgress } from "./writer.js";
@@ -46,6 +47,11 @@ export interface SetupOptions {
   newAccount?: boolean;
   name?: string;
   allowAllTools?: boolean;
+  /**
+   * Answer every yes/no confirmation with its default and skip the prompt.
+   * Also implied when stdin is not a TTY (pipe/agent/CI). See `./confirm.ts`.
+   */
+  yes?: boolean;
 }
 
 /**
@@ -723,6 +729,19 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
   console.clear();
   console.log(messages.header());
 
+  // Non-interactive mode: `--yes`, or no TTY (pipe / coding agent / CI). Every
+  // yes/no confirmation below resolves to its default instead of blocking on a
+  // keypress that will never arrive. Selection/text prompts are unaffected —
+  // suppress those with their own flags (--api-key, --agents, --skip-context…).
+  const assumeYes = shouldAssumeYes(options.yes, process.stdin.isTTY);
+  if (assumeYes) {
+    p.log.info(
+      options.yes
+        ? "Non-interactive mode (--yes): using the default answer for each confirmation."
+        : "No interactive terminal detected: using the default answer for each confirmation.",
+    );
+  }
+
   // Check existing configuration
   const existingConfig = loadConfig();
   const alreadyConfigured = isConfigured();
@@ -1005,7 +1024,7 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
   if (skillsStatus.installed && !options.force) {
     p.log.success(`Skills already installed (${skillsStatus.location})`);
 
-    const reinstall = await p.confirm({
+    const reinstall = await confirmOrDefault(assumeYes, {
       message: "Reinstall skills?",
       initialValue: false,
     });
@@ -1397,7 +1416,7 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
   console.log("");
 
   // Step 6: Confirm and execute
-  const shouldProceed = await p.confirm({
+  const shouldProceed = await confirmOrDefault(assumeYes, {
     message: "Proceed with setup?",
     initialValue: true,
   });
@@ -1486,7 +1505,10 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
     const message = allowAll
       ? "Allowlist EVERY Harmony tool without confirmation, including destructive ones (delete/archive/api-key/invite)?"
       : "Allowlist common Harmony tools (reads + create/update/move/comment) so /hmy doesn't prompt each time? Destructive tools (delete/archive/api-key/invite) will still ask.";
-    const allowTools = await p.confirm({ message, initialValue: true });
+    const allowTools = await confirmOrDefault(assumeYes, {
+      message,
+      initialValue: true,
+    });
     if (p.isCancel(allowTools)) {
       p.cancel("Setup cancelled.");
       process.exit(0);