ucu-mcp 0.3.7 → 0.3.9

package/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.8] - 2026-06-08
+
+### Fixed
+
+- `focus_app` no longer trips the user-activity pause. It used to be classified as `"other"` (neither observe nor input) so a recent mouse movement could block `focus_app` for 2 s; it is now in `OBSERVE_ACTIONS`, matching the production `withSafety` default. Symptom: OpenCode could not switch the active target app (e.g. CC Switch) without retrying until the cursor had been still for 2 s.
+- `doctor` native-helper path resolution now checks `process.argv[1]` (npm / npx / global install), walks `import.meta.url` up to 4 levels, and falls back to `npm root -g`. Previously, when the MCP client launched `ucu-mcp` from a cwd other than the project root (the common case for `npx ucu-mcp`), the helper binaries would report as missing even though they were in the tarball. The new report includes `path` and a `tried[]` list so the model can see what was checked.
+- `doctor` recommendations now list each missing macOS permission on its own line, name the host terminal app (so the user knows which entry to grant in System Settings), and add an Electron AX hint for the common case where `list_windows` returns `[]` even with Accessibility granted.
+
+### Tests
+
+- `safety-guard`: `focus_app` is in `OBSERVE_ACTIONS`; `classifyAction("focus_app") === "observe"`; `withSafety`'s default `skipUserActivityPause` lets the call through even mid user-activity.
+- `errors`: `WindowNotFoundError` preserves an inline `hint` field set by the platform layer, surfaced in the MCP error response.
+- `macos-platform`: OCR JXA `"Failed to load screenshot image"` is re-thrown as `CaptureError` with a hint pointing at the missing Screen Recording permission (the typical cause is `screencapture` writing a 0-byte file when TCC denies Screen Recording, not the helper binary being absent).
+- `tools-layer`: `doctor` report carries `terminalApp` and the richer `nativeHelpers = { cgevent, ocr } = { ok, path, tried[] }` shape.
+
 ## [0.3.7] - 2026-06-07
 
 ### Fixed

package/dist/src/mcp/tools.js

@@ -94,13 +94,21 @@ function errorDetails(error) {
     const err = error instanceof Error ? error : new Error(String(error));
     const code = error instanceof UcuError ? error.code : "UNKNOWN_ERROR";
     const retryable = error instanceof UcuError ? error.retryable : false;
-    return {
+    // Some platform errors carry an inline `hint` field (added by macos.ts focusApp
+    // for the Electron AX case, etc.). Surface it under `hint` so the model can
+    // see remediation without parsing the message string.
+    const inlineHint = err.hint;
+    const details = {
         name: err.name,
         code,
         retryable,
         message: err.message,
         recovery: recoveryHint(code),
     };
+    if (typeof inlineHint === "string" && inlineHint.length > 0) {
+        details.hint = inlineHint;
+    }
+    return details;
 }
 let _actionCounter = 0;
 function nextActionId() {
@@ -281,7 +289,28 @@ export function registerTools(server) {
         includeMinimized: z.boolean().optional().describe("Include minimized windows"),
     }, async (params) => {
         const windows = await withSafety({ action: "list_windows", params: {}, requiresAccessibility: true, execute: () => getPlatform().listWindows(params.includeMinimized) });
-        return { content: [{ type: "text", text: JSON.stringify(windows, null, 2) }] };
+        // Attach a diagnostic hint when the result is empty so the model can
+        // tell the difference between "no windows are open" and "AX enumeration
+        // failed for the target app" (common with Electron apps like CC Switch,
+        // VS Code, Discord). The windows list itself is the source of truth; the
+        // hint is advisory only.
+        let diagnostics;
+        if (windows.length === 0) {
+            let accessibility = "unknown";
+            try {
+                const { checkPermission } = await import("../safety/permissions.js");
+                const { granted } = await checkPermission("accessibility");
+                accessibility = granted ? "granted" : "denied";
+            }
+            catch { /* keep unknown */ }
+            const axNote = accessibility === "denied"
+                ? "Accessibility is currently denied to this terminal — grant it via System Settings > Privacy & Security > Accessibility, then retry."
+                : accessibility === "granted"
+                    ? "Accessibility is granted. If you expected a specific app to appear here, it is likely an Electron app whose AX tree is not exposed to System Events. Pixel-level workaround: call screenshot, then ocr to locate the target UI text and get its bounding box, then click(x, y) at those screen coordinates. Alternatively, modify the app's config file or database directly."
+                    : "Accessibility status is unknown. Run `doctor` first to verify.";
+            diagnostics = { hint: `list_windows returned 0 windows. ${axNote}`, accessibility };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(diagnostics ? { windows, diagnostics } : windows, null, 2) }] };
     });
     registry.register("list_windows");
     registerTool("list_apps", "List all running applications", {}, async () => {
@@ -384,55 +413,104 @@ export function registerTools(server) {
     });
     registry.register("drag");
     registerTool("doctor", "Check system permissions, native helpers, and client readiness", {}, async () => {
-        const { checkPermissions } = await import("../safety/permissions.js");
+        const { checkPermissions, getPermissionInstructions, getTerminalAppName } = await import("../safety/permissions.js");
         const { MacOSPlatform: MacPlat } = await import("../platform/macos.js");
-        const { existsSync } = await import("node:fs");
-        const { join, dirname } = await import("node:path");
+        const { existsSync, statSync } = await import("node:fs");
+        const { join, dirname, resolve } = await import("node:path");
         const { fileURLToPath } = await import("node:url");
         const { execFileSync } = await import("node:child_process");
         const permissions = await checkPermissions();
         const screenLocked = process.platform === "darwin" ? new MacPlat().isScreenLocked?.() ?? false : false;
-        let nativeHelpers;
-        if (process.platform === "darwin") {
+        const termApp = process.platform === "darwin" ? getTerminalAppName() : undefined;
+        // Resolve native helper binaries across every install layout we have seen:
+        //  - dev: process.cwd() === project root
+        //  - npm install --prefix X: argv[1] is in X/node_modules/ucu-mcp/...
+        //  - global install via npm: argv[1] is in $(npm root -g)/ucu-mcp/...
+        //  - npx: argv[1] is in ~/.npm/_npx/.../node_modules/ucu-mcp/...
+        //  - bin/ucu-mcp.js is the entry; dist/src/*/tools.js is the module path
+        function resolveHelperPath(relParts) {
+            const tried = [];
+            const tryPaths = [];
             const moduleDir = dirname(fileURLToPath(import.meta.url));
-            const checkPaths = (subdirs) => {
-                const paths = [
-                    join(process.cwd(), ...subdirs),
-                    join(moduleDir, "..", ...subdirs),
-                    join(moduleDir, "..", "..", ...subdirs),
-                ];
-                return paths.some(p => { try {
-                    return existsSync(p);
+            const argv1 = process.argv[1] ? resolve(process.argv[1]) : "";
+            const argv1Dir = argv1 ? dirname(argv1) : "";
+            // (1) process.cwd() — dev invocation
+            tryPaths.push(join(process.cwd(), ...relParts));
+            // (2) argv[1] dir — npm / npx / global
+            if (argv1Dir) {
+                tryPaths.push(join(argv1Dir, ...relParts));
+                tryPaths.push(join(argv1Dir, "..", ...relParts));
+                tryPaths.push(join(argv1Dir, "..", "..", ...relParts));
+            }
+            // (3) module dir — dist/bin or dist/src/mcp; walk up to 4 levels
+            tryPaths.push(join(moduleDir, "..", ...relParts));
+            tryPaths.push(join(moduleDir, "..", "..", ...relParts));
+            tryPaths.push(join(moduleDir, "..", "..", "..", ...relParts));
+            tryPaths.push(join(moduleDir, "..", "..", "..", "..", ...relParts));
+            // (4) npm root -g for global install (best effort)
+            if (process.platform === "darwin") {
+                try {
+                    const npmRoot = execFileSync("npm", ["root", "-g"], { encoding: "utf-8", timeout: 2000 }).trim();
+                    if (npmRoot) {
+                        tryPaths.push(join(npmRoot, "ucu-mcp", ...relParts));
+                    }
                 }
-                catch {
-                    return false;
-                } });
-            };
+                catch { /* npm not on PATH is fine */ }
+            }
+            for (const p of tryPaths) {
+                tried.push(p);
+                try {
+                    if (existsSync(p) && statSync(p).isFile())
+                        return { path: p, tried };
+                }
+                catch { /* skip */ }
+            }
+            return { path: null, tried };
+        }
+        let nativeHelpers;
+        if (process.platform === "darwin") {
+            const cgevent = resolveHelperPath(["native", "cgevent", "cgevent-helper"]);
+            const ocr = resolveHelperPath(["native", "ocr", "ocr-helper"]);
+            const windowlist = resolveHelperPath(["native", "windowlist", "windowlist-helper"]);
             nativeHelpers = {
-                cgevent: checkPaths(["native", "cgevent", "cgevent-helper"]),
-                ocr: checkPaths(["native", "ocr", "ocr-helper"]),
+                cgevent: { ok: cgevent.path !== null, path: cgevent.path, tried: cgevent.tried.slice(0, 3) },
+                ocr: { ok: ocr.path !== null, path: ocr.path, tried: ocr.tried.slice(0, 3) },
+                windowlist: { ok: windowlist.path !== null, path: windowlist.path, tried: windowlist.tried.slice(0, 3) },
             };
         }
         let readiness = "ready";
         const issues = [];
         if (!permissions.granted) {
             readiness = "blocked";
-            issues.push("Missing macOS permissions: " + permissions.missing.join(", "));
+            for (const m of (permissions.missing ?? [])) {
+                issues.push(`Missing macOS permission: ${m}`);
+            }
         }
         if (screenLocked) {
             readiness = "blocked";
             issues.push("Screen is locked");
         }
         if (process.platform === "darwin" && nativeHelpers) {
-            if (!nativeHelpers.cgevent) {
+            if (!nativeHelpers.cgevent.ok) {
                 readiness = readiness === "ready" ? "degraded" : readiness;
-                issues.push("Native CGEvent helper not found (input synthesis may crash on macOS Sequoia+)");
+                issues.push("Native CGEvent helper not found (input synthesis may crash on macOS Sequoia+). Run `npm run build` to compile it, or reinstall ucu-mcp so the helper ships from the tarball.");
             }
-            if (!nativeHelpers.ocr) {
+            if (!nativeHelpers.ocr.ok) {
                 readiness = readiness === "ready" ? "degraded" : readiness;
-                issues.push("Native OCR helper not found (OCR may fail on macOS Sequoia+)");
+                issues.push("Native OCR helper not found (OCR may fail on macOS Sequoia+). Run `npm run build` to compile it, or reinstall ucu-mcp so the helper ships from the tarball.");
+            }
+            if (!nativeHelpers.windowlist.ok) {
+                readiness = readiness === "ready" ? "degraded" : readiness;
+                issues.push("Native windowlist helper not found (window enumeration will fall back to slow JXA). Run `npm run build` to compile it.");
             }
         }
+        // Heuristic AX hint: if Accessibility is granted but list_windows consistently
+        // returns empty for the only app the model cared about, the model has likely
+        // hit the Electron AX limitation (Electron windows do not expose AX to System
+        // Events unless Accessibility is also granted to the Electron process itself,
+        // and the app has accessibility features enabled). This block is read-only —
+        // we never hit JXA here because the doctor must stay fast and side-effect free.
+        const electronHint = "If the target app is Electron (e.g. CC Switch, VS Code, Discord), list_windows may return [] even with Accessibility granted to your terminal. Grant Accessibility to the Electron app itself in System Settings > Privacy & Security > Accessibility, and restart the app. Pixel-level workaround: use screenshot + ocr to locate UI elements by text, then click(x, y) at the detected bounding box coordinates. Alternatively, modify the app\'s config file or database directly.";
         const clients = {};
         for (const bin of ["claude", "codex", "opencode", "npx"]) {
             try {
@@ -445,16 +523,27 @@ export function registerTools(server) {
         }
         const recommendations = [];
         if (readiness === "blocked") {
-            recommendations.push("Grant missing permissions in System Settings > Privacy & Security, then restart the MCP client.");
+            for (const m of (permissions.missing ?? [])) {
+                const app = termApp ?? "your terminal app";
+                recommendations.push(`${m}: ${getPermissionInstructions(m)} (Grant to ${app}.)`);
+            }
+            if (screenLocked)
+                recommendations.push("Unlock the screen, then retry.");
         }
-        else if (readiness === "degraded") {
-            if (nativeHelpers && (!nativeHelpers.cgevent || !nativeHelpers.ocr)) {
-                recommendations.push("Run 'npm run build' to compile native Swift helpers.");
+        if (readiness !== "ready") {
+            if (process.platform === "darwin" && nativeHelpers && (!nativeHelpers.cgevent.ok || !nativeHelpers.ocr.ok)) {
+                recommendations.push("Run `npm run build` in the ucu-mcp project to compile native Swift helpers (cgevent-helper, ocr-helper, windowlist-helper).");
+            }
+            if (process.platform === "darwin" && nativeHelpers && !nativeHelpers.windowlist.ok) {
+                recommendations.push("windowlist helper missing — list_windows will fall back to JXA (~3-6s, unreliable for Electron). Run `npm run build`.");
             }
         }
-        else {
+        if (readiness === "ready") {
             recommendations.push("All checks passed. MCP client can proceed with automation.");
         }
+        else if (process.platform === "darwin") {
+            recommendations.push(electronHint);
+        }
         const report = {
             readiness,
             issues: issues.length > 0 ? issues : undefined,
@@ -463,6 +552,7 @@ export function registerTools(server) {
             node: process.version,
             permissions,
             screenLocked,
+            terminalApp: termApp,
             nativeHelpers,
             clients,
             safety: {

package/dist/src/platform/macos.d.ts

@@ -1,5 +1,15 @@
 import type { Platform, ScreenRegion, ScreenSize, CursorPosition, WindowInfo, WindowState, OcrResult, FindElementOptions, FindElementResponse, AppInfo, AppTarget, BrowserContext, ScreenshotOptions } from "./base.js";
+export interface MacOSPlatformOptions {
+    /**
+     * Override native helper resolution.
+     * - Map of folder name to absolute binary path to inject a specific helper.
+     * - Set a value to null to skip that helper (force JXA fallback).
+     * Used by tests to control native helper behavior without filesystem tricks.
+     */
+    nativeHelperPaths?: Record<string, string | null>;
+}
 export declare class MacOSPlatform implements Platform {
+    private readonly _nativeHelperPaths;
     private readonly elementCache;
     private readonly elementCacheTtlMs;
     private readonly elementCacheMaxSize;
@@ -7,6 +17,7 @@ export declare class MacOSPlatform implements Platform {
     private windowCache;
     private activeTarget;
     private savedFocus;
+    constructor(options?: MacOSPlatformOptions);
     /** Remove expired entries from the element cache. */
     private evictExpiredCacheEntries;
     /** Evict oldest entries when cache exceeds the maximum size (LRU-style). */
@@ -27,6 +38,9 @@ export declare class MacOSPlatform implements Platform {
     focusApp(app: string): Promise<AppTarget>;
     getActiveBrowserContext(app?: string): Promise<BrowserContext | undefined>;
     listWindows(_includeMinimized?: boolean): Promise<WindowInfo[]>;
+    private listWindowsNative;
+    private resolveNativeHelper;
+    private listWindowsJxa;
     getWindowState(windowId?: string, depth?: number, includeBounds?: boolean): Promise<WindowState>;
     click(x: number, y: number, button?: "left" | "right" | "middle", doubleClick?: boolean): Promise<void>;
     move(x: number, y: number): Promise<void>;

package/dist/src/platform/macos.js

@@ -4,6 +4,10 @@ import { promisify } from "node:util";
 import { captureFullScreen, captureRegion } from "../utils/screenshot.js";
 import { click as inputClick, doubleClick as inputDoubleClick, move as inputMove, drag as inputDrag, scroll as inputScroll, typeText, pressShortcut } from "../utils/input.js";
 import { CaptureError, ElementNotFoundError, InputSynthesisError, PermissionError, PlatformError, TargetStaleError, UcuError, WindowNotFoundError } from "../util/errors.js";
+import { existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+const __macosDirname = dirname(fileURLToPath(import.meta.url));
 const execFileAsync = promisify(execFile);
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
@@ -59,6 +63,7 @@ function selectWindowForApp(windows, requestedApp) {
         windows.find((window) => appNameMatches(window.processName, requestedApp));
 }
 export class MacOSPlatform {
+    _nativeHelperPaths;
     elementCache = new Map();
     elementCacheTtlMs = 30_000;
     elementCacheMaxSize = 100;
@@ -66,6 +71,9 @@ export class MacOSPlatform {
     windowCache;
     activeTarget;
     savedFocus;
+    constructor(options) {
+        this._nativeHelperPaths = options?.nativeHelperPaths;
+    }
     // ── Element Cache Management ────────────────────────────────────────────
     /** Remove expired entries from the element cache. */
     evictExpiredCacheEntries() {
@@ -248,7 +256,23 @@ export class MacOSPlatform {
             await new Promise((resolve) => setTimeout(resolve, 150));
         } while (Date.now() < deadline);
         if (!target) {
-            throw new WindowNotFoundError(app);
+            // Wrap with a more diagnostic message: many real-world failures are
+            // Electron apps that do not expose their AX tree to System Events
+            // (CC Switch, VS Code, Discord, Slack). WindowNotFoundError carries the
+            // app name so the tool handler can surface a remediation hint. The
+            // bare WindowNotFoundError("CC Switch") was indistinguishable from
+            // "the app is not running", which led models to retry forever.
+            const err = new WindowNotFoundError(app);
+            err.hint =
+                "list_windows returned no match for this app. If the app is running, " +
+                    "the most likely cause is that it is an Electron app whose AX tree is " +
+                    "not exposed to System Events (System Settings > Privacy & Security > " +
+                    "Accessibility must be granted to the Electron process itself, not just " +
+                    "to the host terminal). Pixel-level workaround: call screenshot to " +
+                    "capture the screen, then ocr to locate UI text and get its bounding " +
+                    "box coordinates, then click(x, y) at those screen coordinates. " +
+                    "Alternatively, modify the app's config file or database directly.";
+            throw err;
         }
         this.activeTarget = {
             targetId: randomUUID(),
@@ -320,11 +344,81 @@ export class MacOSPlatform {
             }));
         }
         try {
-            // Use System Events instead of CGWindowListCopyWindowInfo.
-            // The CoreGraphics API returns CFArrayRef/CFDictionaryRef which JXA
-            // cannot iterate reliably — CFArrayGetCount works but objectAtIndex
-            // does not. System Events JXA is slower (~3-6s) but correct.
-            const jxaScript = `
+            // Try native Swift helper first (CGWindowListCopyWindowInfo, ~1ms).
+            // Falls back to JXA System Events if the helper is not available.
+            // The native helper reliably enumerates ALL windows including Electron
+            // apps, whereas JXA relies on System Events AX which is inconsistent
+            // for Chromium-rendered windows.
+            let windows;
+            const nativeResult = this.listWindowsNative();
+            if (nativeResult !== null) {
+                windows = nativeResult;
+            }
+            else {
+                windows = await this.listWindowsJxa();
+            }
+            this.windowCache = {
+                cachedAt: Date.now(),
+                windows: windows.map((window) => ({
+                    ...window,
+                    bounds: { ...window.bounds },
+                })),
+            };
+            return windows;
+        }
+        catch {
+            // Fallback: return empty list if both methods fail
+            return [];
+        }
+    }
+    listWindowsNative() {
+        try {
+            const helperPath = this.resolveNativeHelper("windowlist", "windowlist-helper");
+            if (!helperPath)
+                return null;
+            const out = execFileSync(helperPath, [], {
+                encoding: "utf-8",
+                timeout: 5000,
+            });
+            const parsed = JSON.parse(out.trim());
+            if (parsed.error)
+                return null;
+            return parsed.windows.map(w => ({
+                id: w.id,
+                title: w.title,
+                processName: w.processName,
+                pid: w.pid,
+                bounds: w.bounds,
+                isMinimized: !w.isOnScreen,
+                isOnScreen: w.isOnScreen,
+            }));
+        }
+        catch {
+            return null;
+        }
+    }
+    resolveNativeHelper(folder, binary) {
+        // Test injection: if the caller provided explicit paths, use those
+        // instead of hitting the filesystem.
+        if (this._nativeHelperPaths && folder in this._nativeHelperPaths) {
+            const override = this._nativeHelperPaths[folder];
+            // null means "skip native, force JXA fallback"
+            return override === null ? null : override;
+        }
+        // dev: src/platform/macos.ts → native/<folder>/<binary>
+        // prod: dist/src/platform/macos.js → native/<folder>/<binary>
+        const candidates = [
+            join(__macosDirname, "..", "..", "native", folder, binary),
+            join(__macosDirname, "..", "..", "..", "native", folder, binary),
+        ];
+        for (const p of candidates) {
+            if (existsSync(p))
+                return p;
+        }
+        return null;
+    }
+    async listWindowsJxa() {
+        const jxaScript = `
         var se = Application('System Events');
         var result = [];
         var procs = se.processes();
@@ -358,24 +452,11 @@ export class MacOSPlatform {
         }
         JSON.stringify(result);
       `;
-            const jxaOut = execFileSync("osascript", [
-                "-l", "JavaScript",
-                "-e", jxaScript
-            ], { encoding: "utf-8", timeout: 15000 });
-            const windows = JSON.parse(jxaOut.trim());
-            this.windowCache = {
-                cachedAt: Date.now(),
-                windows: windows.map((window) => ({
-                    ...window,
-                    bounds: { ...window.bounds },
-                })),
-            };
-            return windows;
-        }
-        catch {
-            // Fallback: return empty list if JXA fails
-            return [];
-        }
+        const jxaOut = execFileSync("osascript", [
+            "-l", "JavaScript",
+            "-e", jxaScript
+        ], { encoding: "utf-8", timeout: 15000 });
+        return JSON.parse(jxaOut.trim());
     }
     async getWindowState(windowId, depth, includeBounds = true) {
         if (!windowId || windowId === this.activeTarget?.windowId) {
@@ -779,8 +860,18 @@ export class MacOSPlatform {
     `;
         const out = execFileSync("osascript", ["-l", "JavaScript", "-e", jxaScript], { encoding: "utf-8", timeout: 30000 }).trim();
         const parsed = JSON.parse(out);
-        if (parsed.error)
-            throw new CaptureError(`ocr failed: ${parsed.error}`);
+        if (parsed.error) {
+            // Distinguish permission-class failures from real Vision errors.
+            // screencapture writes a 0-byte file when Screen Recording is not granted,
+            // and the JXA NSImage init then fails with "Failed to load screenshot image".
+            // Surface that as a PermissionError hint so the model can suggest the right fix.
+            const hint = parsed.error === "Failed to load screenshot image"
+                ? " (the screenshot file is empty or unreadable — Screen Recording permission is most likely missing; run `doctor` and grant Screen Recording to the host terminal, then retry)"
+                : parsed.error === "Failed to get CGImage from screenshot"
+                    ? " (the screenshot could not be decoded — likely an empty capture; check Screen Recording permission)"
+                    : "";
+            throw new CaptureError(`ocr failed: ${parsed.error}${hint}`);
+        }
         const imgWidth = buf.readUInt32BE(16);
         const scaleFactorX = screenSize.width / (region ? region.width : (imgWidth / scaleFactor));
         const elements = parsed.elements.map((el) => ({

package/dist/src/safety/guard.js

@@ -100,6 +100,10 @@ export const OBSERVE_ACTIONS = new Set([
     "wait_for_element",
     "doctor",
     "clipboard_read",
+    // focus_app only sets the active target context via AppleScript activate
+    // and an AX window lookup — it does not synthesize mouse or keyboard input,
+    // so the user-activity pause must not block it. (OpenCode 0.3.7 follow-up)
+    "focus_app",
 ]);
 /** Actions that synthesize user input — need full user-activity protection. */
 export const INPUT_ACTIONS = new Set([

package/dist/src/safety/permissions.d.ts

@@ -8,6 +8,10 @@ export interface PermissionDetail {
     granted: boolean;
     instructions: string;
 }
+/**
+ * Get the name of the terminal app that the user needs to authorize.
+ */
+export declare function getTerminalAppName(): string;
 export declare function checkPermissions(): Promise<PermissionCheckResult>;
 export declare function checkPermission(type: "accessibility" | "screenRecording"): Promise<{
     granted: boolean;

package/dist/src/safety/permissions.js

@@ -4,7 +4,7 @@ const execFileAsync = promisify(execFile);
 /**
  * Get the name of the terminal app that the user needs to authorize.
  */
-function getTerminalAppName() {
+export function getTerminalAppName() {
     // Walk up the process tree to find the terminal emulator
     const ppid = process.ppid;
     // Common terminal app names

package/native/windowlist/main.swift

@@ -0,0 +1,74 @@
+import CoreGraphics
+import Foundation
+
+// Window enumeration using CGWindowListCopyWindowInfo (WindowServer-level).
+// Replaces JXA System Events enumeration which is slow (3-6s) and unreliable
+// for Electron apps. CGWindowListCopyWindowInfo sees ALL windows regardless
+// of whether the app exposes an AX tree.
+
+struct WinInfo: Encodable {
+    let id: String
+    let title: String
+    let processName: String
+    let pid: Int32
+    let bounds: Bounds
+    let isOnScreen: Bool
+    let windowNumber: Int
+}
+
+struct Bounds: Encodable {
+    let x: Double
+    let y: Double
+    let width: Double
+    let height: Double
+}
+
+struct Output: Encodable {
+    let windows: [WinInfo]
+    let error: String?
+}
+
+let options: CGWindowListOption = .optionOnScreenOnly
+guard let windowList = CGWindowListCopyWindowInfo(options, kCGNullWindowID) as? [[String: Any]] else {
+    let out = Output(windows: [], error: "CGWindowListCopyWindowInfo returned nil")
+    FileHandle.standardOutput.write(try! JSONEncoder().encode(out))
+    exit(0)
+}
+
+var results: [WinInfo] = []
+
+for info in windowList {
+    guard let pid = info[kCGWindowOwnerPID as String] as? Int32,
+          let windowNumber = info[kCGWindowNumber as String] as? Int,
+          let layer = info[kCGWindowLayer as String] as? Int
+    else { continue }
+
+    // Skip non-normal layers (overlay, screen saver, etc.)
+    if layer != 0 { continue }
+
+    let boundsDict = info[kCGWindowBounds as String] as? [String: Any]
+    let w = boundsDict?["Width"] as? Double ?? 0
+    let h = boundsDict?["Height"] as? Double ?? 0
+    if w == 0 || h == 0 { continue }
+
+    let processName = (info[kCGWindowOwnerName as String] as? String) ?? ""
+    if processName.isEmpty { continue }
+
+    let title = (info[kCGWindowName as String] as? String) ?? ""
+    let isOnScreen = (info[kCGWindowIsOnscreen as String] as? Bool) ?? true
+    let x = (boundsDict?["X"] as? Double) ?? 0
+    let y = (boundsDict?["Y"] as? Double) ?? 0
+
+    results.append(WinInfo(
+        id: "\(processName)/win\(windowNumber)",
+        title: title,
+        processName: processName,
+        pid: pid,
+        bounds: Bounds(x: x, y: y, width: w, height: h),
+        isOnScreen: isOnScreen,
+        windowNumber: windowNumber
+    ))
+}
+
+let output = Output(windows: results, error: nil)
+FileHandle.standardOutput.write(try! JSONEncoder().encode(output))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucu-mcp",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "description": "MCP server for Universal Computer Use — desktop automation for AI agents via Model Context Protocol",
   "type": "module",
   "bin": {
@@ -27,7 +27,7 @@
     "test:macos-gui": "UCU_MACOS_GUI_SMOKE=1 vitest run tests/integration/macos-gui-smoke.test.ts",
     "test:client-cli": "UCU_CLIENT_CLI_SMOKE=1 vitest run tests/integration/client-cli-smoke.test.ts",
     "prepublishOnly": "npx vitest run tests/unit/ && npm run build",
-    "build:native": "cd native/cgevent && swiftc -O -o cgevent-helper main.swift -framework CoreGraphics -framework Foundation && cd ../ocr && swiftc -O -o ocr-helper main.swift -framework Vision -framework AppKit"
+    "build:native": "cd native/cgevent && swiftc -O -o cgevent-helper main.swift -framework CoreGraphics -framework Foundation && cd ../ocr && swiftc -O -o ocr-helper main.swift -framework Vision -framework AppKit && cd ../windowlist && swiftc -O -o windowlist-helper main.swift -framework CoreGraphics -framework Foundation"
   },
   "keywords": [
     "mcp",