fix: 0.2.1 — macOS capsule.raise 真正等焦点切换完成

P0 (macOS): subagent 真机实验发现 capsule.raise 报 ok=true 但
validate_geometry 立刻看到 is_foreground=false 死锁。

根因：Swift helper 的 activate(pid:) 是 fire-and-forget：
  NSWorkspace.shared.runningApplications.first(...)?.activate(...)
  return ["ok": true]
NSWorkspace activate 是异步的，macOS 14+ Stage Manager / 焦点窃取
保护下 100-500ms 内 frontmostApplication 仍是调用者。JS 端 sleep(180)
不够（osascript 路径注释明确说"100-200ms 误报，500ms 才稳"，但
helper 路径没同步改）。

修：
- Swift helper 新 activateAndWaitForeground(pid, timeoutMs=1500)：
  发出 activate 后 polling NSWorkspace.frontmostApplication 直到
  匹配目标 PID 或 timeout。返回 (success, frontPid)。
- window.activate / window.raise 用此函数；ok=true 时返
  {ok:true, frontmost_pid}；超时返
  {ok:false, reason:"foreground_timeout", target_pid, frontmost_pid, hint}。
  hint 明确告诉调用方"macOS 焦点窃取保护，让用户手动 cmd+tab"。
- moveWindow 末尾的 activate 也用新函数（之前 usleep(120) 同样不够）。
- darwin-helper.raiseWindow 检查 ok=false 抛 VisionMcpError(GEOMETRY_MISMATCH)
  带 details.reason 让上层 ERROR_HINTS 分情况展示。
- ERROR_HINTS.GEOMETRY_MISMATCH 重写：
  · foreground_timeout → 明确说 repair_minimal 救不了，要用户 cmd+tab
  · 尺寸 → repair_minimal
  · 窗口拖出 → capsule.migrate_window
  之前一刀切"用 repair_minimal"误导 agent 反复无效尝试。

验证（手动 JSON-RPC 测）：
  > {"method":"window.activate","params":{"handle":"96680:0"}}  # Notes
  < {"ok":true,"frontmost_pid":96680}                            # 同步等到切完
  之前会立即返 {"ok":true} 而 frontmost 还是 Claude Code/Terminal。

仍是 patch 级（行为更准但 API 不变）。56/56 tests pass。
helper 重编译（254KB → 255KB）。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Haruhiyuki

.claude-plugin/marketplace.json

@@ -1,6 +1,6 @@
 {
   "name": "vision-mcp",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Vision-MCP plugins — 桌面 GUI 操作的性能 / 长期成本优化层",
   "owner": {
     "name": "Haruhiyuki",
@@ -11,7 +11,7 @@
       "name": "vision-mcp",
       "description": "Vision-MCP: 让 Agent 在使用桌面软件时沉淀指令化操作方法的框架（macOS + Windows）",
       "source": "./",
-      "version": "0.2.0",
+      "version": "0.2.1",
       "keywords": [
         "mcp",
         "vision",

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "vision-mcp",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Vision-MCP: 视觉为主的桌面 GUI 操作 MCP server + Skill。Agent 可像人一样使用真实桌面应用（截图 → 视觉/AX 双轨识别 → click/type/key），支持持续修正 + 安全审批。",
   "author": {
     "name": "Vision-MCP Authors",

native/macos/src/main.swift

@@ -597,6 +597,24 @@ func activate(pid: pid_t) {
     }
 }
 
+/// activate + polling 直到目标 PID 变成 frontmostApplication，或 timeoutMs 超时。
+/// macOS 14+ Stage Manager / 焦点窃取保护下，NSWorkspace.activate 是异步的——立刻调用
+/// validate_geometry 会看到 is_foreground=false，给上层误判。这里同步等到 NSWorkspace
+/// 真切到目标 PID 才返回。
+/// 返回 (success, frontmost_pid_at_exit)。success=false 时上层应直接抛 error。
+func activateAndWaitForeground(pid: pid_t, timeoutMs: Int = 1500) -> (Bool, pid_t) {
+    activate(pid: pid)
+    let deadline = Date().addingTimeInterval(Double(timeoutMs) / 1000.0)
+    var frontPid: pid_t = NSWorkspace.shared.frontmostApplication?.processIdentifier ?? 0
+    if frontPid == pid { return (true, frontPid) }
+    while Date() < deadline {
+        usleep(60_000) // 60ms
+        frontPid = NSWorkspace.shared.frontmostApplication?.processIdentifier ?? 0
+        if frontPid == pid { return (true, frontPid) }
+    }
+    return (false, frontPid)
+}
+
 func moveWindow(handle: String, rect: CGRect) -> [String: Any]? {
     guard let (_, axWin, _) = findWindow(handle: handle) else { return nil }
     if axBoolAttr(axWin, kAXMinimizedAttribute) == true {
@@ -609,8 +627,8 @@ func moveWindow(handle: String, rect: CGRect) -> [String: Any]? {
     AXUIElementSetAttributeValue(axWin, kAXPositionAttribute as CFString, posVal)
     AXUIElementSetAttributeValue(axWin, kAXSizeAttribute as CFString, sizeVal)
     let pid = pid_t(handle.split(separator: ":").first!)!
-    activate(pid: pid)
-    usleep(120_000)
+    // 同步等到 PID 真切前台。120ms 在 macOS 14+ 焦点窃取保护下经常不够。
+    _ = activateAndWaitForeground(pid: pid)
     if let (_, _, desc) = findWindow(handle: handle) {
         return toWindowInfo(desc)
     }
@@ -926,14 +944,29 @@ func handle(method: String, params: [String: Any]) -> Any {
     case "window.activate":
         guard let handle = params["handle"] as? String,
               let pid = pid_t(handle.split(separator: ":").first.map(String.init) ?? "") else { return ["error": "bad handle"] }
-        activate(pid: pid)
-        return ["ok": true]
+        let (ok, frontPid) = activateAndWaitForeground(pid: pid)
+        if ok { return ["ok": true, "frontmost_pid": Int(frontPid)] }
+        // 超时——给上层提供详细诊断让 agent 知道为什么 raise 失败
+        return [
+            "ok": false,
+            "reason": "foreground_timeout",
+            "target_pid": Int(pid),
+            "frontmost_pid": Int(frontPid),
+            "hint": "macOS 焦点窃取保护拦截了 activation；调用者可能持续 frontmost。让用户手动 cmd+tab 到目标 app，或在 Claude Code 中先点击桌面再重试"
+        ]
     case "window.raise":
         // window.raise 等价于 window.activate（保留向后兼容）
         guard let handle = params["handle"] as? String,
               let pid = pid_t(handle.split(separator: ":").first.map(String.init) ?? "") else { return ["error": "bad handle"] }
-        activate(pid: pid)
-        return ["ok": true]
+        let (ok, frontPid) = activateAndWaitForeground(pid: pid)
+        if ok { return ["ok": true, "frontmost_pid": Int(frontPid)] }
+        return [
+            "ok": false,
+            "reason": "foreground_timeout",
+            "target_pid": Int(pid),
+            "frontmost_pid": Int(frontPid),
+            "hint": "macOS 焦点窃取保护拦截了 activation；调用者可能持续 frontmost。让用户手动 cmd+tab 到目标 app，或在 Claude Code 中先点击桌面再重试"
+        ]
     case "ax.dump":
         guard let handle = params["handle"] as? String else { return ["error": "handle required"] }
         let maxNodes = (params["max_nodes"] as? NSNumber)?.intValue ?? 500

native/macos/vision-mcp-helper

@@ -1,5 +1,14 @@
 # @vision-mcp/cli
 
+## 0.2.1
+
+### Patch Changes
+
+- 修复 macOS capsule.raise 报 ok 但窗口没真切前台的死锁。Swift helper 的 `window.activate` / `window.raise` 现在内部 polling 等到目标 PID 真成为 frontmost（timeout 1500ms），超时返回 `{ok: false, reason: "foreground_timeout", target_pid, frontmost_pid, hint}`。JS adapter `raiseWindow` 检查 ok=false 直接抛 `GEOMETRY_MISMATCH` 带详细诊断。`ERROR_HINTS.GEOMETRY_MISMATCH` 改写为分情况提示，明确 foreground_timeout 是焦点窃取保护、repair_minimal 救不了，让用户手动 cmd+tab 一次。
+- Updated dependencies
+  - @vision-mcp/core@0.2.1
+  - @vision-mcp/server@0.2.1
+
 ## 0.2.0
 
 ### Minor Changes

packages/cli/CHANGELOG.md

@@ -1,6 +1,6 @@
 {
   "name": "@vision-mcp/cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Vision-MCP CLI：视觉为主的桌面 GUI 操作 MCP server + 工具集（init / serve / capsule / snapshot / patch / install-helper 等）",
   "keywords": [
     "mcp",
@@ -41,8 +41,8 @@
     "prepublishOnly": "node ./scripts/prepublish.mjs"
   },
   "dependencies": {
-    "@vision-mcp/core": "^0.2.0",
-    "@vision-mcp/server": "^0.2.0",
+    "@vision-mcp/core": "^0.2.1",
+    "@vision-mcp/server": "^0.2.1",
     "yaml": "^2.7.0"
   },
   "repository": {

packages/cli/package.json

@@ -1,5 +1,11 @@
 # @vision-mcp/core
 
+## 0.2.1
+
+### Patch Changes
+
+- 修复 macOS capsule.raise 报 ok 但窗口没真切前台的死锁。Swift helper 的 `window.activate` / `window.raise` 现在内部 polling 等到目标 PID 真成为 frontmost（timeout 1500ms），超时返回 `{ok: false, reason: "foreground_timeout", target_pid, frontmost_pid, hint}`。JS adapter `raiseWindow` 检查 ok=false 直接抛 `GEOMETRY_MISMATCH` 带详细诊断。`ERROR_HINTS.GEOMETRY_MISMATCH` 改写为分情况提示，明确 foreground_timeout 是焦点窃取保护、repair_minimal 救不了，让用户手动 cmd+tab 一次。
+
 ## 0.2.0
 
 ### Minor Changes

packages/core/CHANGELOG.md

@@ -1,6 +1,6 @@
 {
   "name": "@vision-mcp/core",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Vision-MCP 核心库：数据模型、Capsule、Runtime、Repair、Locator、Trace",
   "type": "module",
   "main": "./dist/index.js",

packages/core/package.json

@@ -213,8 +213,23 @@ export class DarwinHelperAdapter implements PlatformAdapter {
   }
 
   async raiseWindow(handle: string): Promise<void> {
-    await this.bridge.request("window.activate", { handle });
-    await sleep(180);
+    // helper 内部 polling 等到目标 PID 真切前台或 timeout（1500ms）。
+    // 之前 sleep(180) 在 macOS 14+ Stage Manager / 焦点窃取保护下经常不够，
+    // 导致 capsule.raise 报 ok=true 但紧接 validate_geometry 看到 is_foreground=false。
+    const r = await this.bridge.request<{
+      ok: boolean;
+      reason?: string;
+      target_pid?: number;
+      frontmost_pid?: number;
+      hint?: string;
+    }>("window.activate", { handle });
+    if (!r.ok) {
+      throw new VisionMcpError(
+        "GEOMETRY_MISMATCH",
+        `raise 失败: ${r.reason ?? "unknown"}（target_pid=${r.target_pid}, frontmost_pid=${r.frontmost_pid}）。${r.hint ?? ""}`,
+        { details: { reason: r.reason, target_pid: r.target_pid, frontmost_pid: r.frontmost_pid } },
+      );
+    }
   }
 
   /**

packages/core/src/platform/darwin-helper.ts

@@ -1,5 +1,13 @@
 # @vision-mcp/server
 
+## 0.2.1
+
+### Patch Changes
+
+- 修复 macOS capsule.raise 报 ok 但窗口没真切前台的死锁。Swift helper 的 `window.activate` / `window.raise` 现在内部 polling 等到目标 PID 真成为 frontmost（timeout 1500ms），超时返回 `{ok: false, reason: "foreground_timeout", target_pid, frontmost_pid, hint}`。JS adapter `raiseWindow` 检查 ok=false 直接抛 `GEOMETRY_MISMATCH` 带详细诊断。`ERROR_HINTS.GEOMETRY_MISMATCH` 改写为分情况提示，明确 foreground_timeout 是焦点窃取保护、repair_minimal 救不了，让用户手动 cmd+tab 一次。
+- Updated dependencies
+  - @vision-mcp/core@0.2.1
+
 ## 0.2.0
 
 ### Minor Changes