codeloop-mcp-server 0.1.47 → 0.1.49

package/dist/index.js

@@ -2,7 +2,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { readFileSync, writeFileSync, existsSync, readdirSync } from "fs";
+import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from "fs";
 function dirHasFile(dir, predicate) {
     try {
         if (!existsSync(dir))
@@ -20,6 +20,7 @@ import { loadConfig } from "./config.js";
 import { validateApiKey, isActivationRequired } from "./auth/api_key.js";
 import { identifyKeySource, buildRevokedKeyDiagnostic } from "./auth/key_source.js";
 import { warmCliCache } from "./auth/cli_cache_warmer.js";
+import { recordInitialisedDir, wasInitialisedAtPath, } from "./auth/init_hint_cache.js";
 import { startUpdateCheck, getUpdateInfo, formatUpdateNotice, getRunningVersion, } from "./auth/update_check.js";
 import { applyUpdate, applyUpdateInputSchema, } from "./tools/apply_update.js";
 import { trackUsage } from "./auth/usage_tracker.js";
@@ -87,6 +88,49 @@ if (!process.env.CODELOOP_PROJECT_DIR &&
         `or set CODELOOP_PROJECT_DIR in your MCP config so future calls auto-resolve. ` +
         `codeloop_init_project will REFUSE to scaffold here.`);
 }
+// 0.1.49 — stale CODELOOP_PROJECT_DIR detection.
+//
+// When init writes a workspace pin into .cursor/mcp.json, it bakes
+// the absolute path of the workspace at the time. If the user later
+// renames or moves the workspace folder (common on Windows when a
+// project graduates from D:\Work\<name> to D:\Repos\<name>), the pin
+// keeps pointing at the old path that no longer exists, and every
+// MCP boot resolves projectDir to a non-existent directory — which
+// silently turns init/verify/gate into no-ops because every "does
+// the .codeloop/ folder exist?" check returns false.
+//
+// We log a single, loud, agent-readable line on stderr so the agent
+// knows to re-run `npx codeloop init` (which rewrites the pin to
+// the workspace's current absolute path — see G8 in the CLI).
+{
+    const pinned = process.env.CODELOOP_PROJECT_DIR;
+    if (pinned) {
+        let stale = false;
+        let reason = "";
+        try {
+            if (!existsSync(pinned)) {
+                stale = true;
+                reason = "path does not exist";
+            }
+            else if (!statSync(pinned).isDirectory()) {
+                stale = true;
+                reason = "path is not a directory";
+            }
+            else if (!existsSync(join(pinned, ".codeloop", "config.json"))) {
+                stale = true;
+                reason = "no .codeloop/config.json under the pinned path";
+            }
+        }
+        catch (e) {
+            stale = true;
+            reason = e.message;
+        }
+        if (stale) {
+            console.error(`[CodeLoop] ⚠ CODELOOP_PROJECT_DIR=${pinned} is stale (${reason}) — falling back to discovery. ` +
+                `Re-run \`npx codeloop init\` from the workspace's current location to rewrite the pin.`);
+        }
+    }
+}
 const config = loadConfig(projectDir);
 const apiKey = process.env.CODELOOP_API_KEY || config.api_key;
 // Pre-warm the npx cache for the `codeloop` CLI in the background so
@@ -135,6 +179,12 @@ const server = new McpServer({
 async function withAuth(fn, tracker) {
     const started = Date.now();
     let outcome = { success: false };
+    // Photometry-DB E2E 8 regression: when the agent passes
+    // `project_dir`/`workspace_root` to a tool, remember that dir for
+    // the lifetime of this MCP process so the init-hint check no
+    // longer false-positives later calls where the call site didn't
+    // forward `dir` to `withInitHint`.
+    rememberInitializedDir(tracker?.cwd);
     try {
         // Local / self-hosted mode (CODELOOP_MODE=local): skip API-key validation
         // entirely. All cloud-side checks are bypassed; usage events are queued
@@ -286,6 +336,33 @@ function buildVersionBanner() {
         text: `[CodeLoop server v${v}]`,
     };
 }
+/**
+ * Last project directory observed to be initialized via an actual
+ * tool call (set by `withAuth`'s tracker — see the .cwd field). The
+ * Photometry-DB E2E session 8 regression was that the agent passed
+ * `project_dir: "D:\\Work\\Photometry DB"` (which IS initialized) on
+ * every call, but the init hint was checking the server's startup
+ * `projectDir` (C:\Users\jiq on Windows) and incorrectly prepending
+ * "This project has not been initialized" to every response. With
+ * this cache, the first authenticated call that hits an initialized
+ * dir silences the hint for the rest of the session — independent of
+ * whether the specific call site forwarded `dir` to `withInitHint`.
+ */
+let lastInitializedDir = null;
+function rememberInitializedDir(dir) {
+    if (!dir)
+        return;
+    if (isProjectInitialized(dir)) {
+        lastInitializedDir = dir;
+        // 0.1.49 — also persist to ~/.codeloop/init-hint-cache.json so
+        // the next MCP server boot (every IDE restart) doesn't false-
+        // positive the "project not initialised" hint until the agent
+        // has happened to forward `dir` to a handler that calls back
+        // into this function. Best-effort; failures swallowed inside
+        // recordInitialisedDir.
+        recordInitialisedDir(dir);
+    }
+}
 function withInitHint(content, dir) {
     // Order matters:
     //   1. Update notice (most actionable signal — CRITICAL stays at top).
@@ -296,7 +373,27 @@ function withInitHint(content, dir) {
     const banner = buildVersionBanner();
     const withUpdate = withUpdateNotice(content);
     const head = [];
-    if (!isProjectInitialized(dir || projectDir)) {
+    // Candidate dirs in priority order:
+    //   1. Explicit `dir` arg from the call site (when the handler
+    //      bothered to thread it through — the verify / capture /
+    //      design_compare etc. handlers do).
+    //   2. `lastInitializedDir` — any dir the agent has already passed
+    //      to *any* CodeLoop tool this session that resolved to an
+    //      initialized config. This catches the long tail of handlers
+    //      that don't forward `dir` (e.g. `recommend_tool`,
+    //      `release_readiness`, `section_status`) so they no longer
+    //      false-positive the hint after init has succeeded once.
+    //   3. The MCP server's startup `projectDir` (often the user's
+    //      home folder on Windows / Cursor — see CODELOOP_PROJECT_DIR
+    //      auto-injection notes in setup-project.ts).
+    const candidates = [dir, lastInitializedDir, projectDir].filter((d) => typeof d === "string" && d.length > 0);
+    // 0.1.49 — also consult the persistent cache so the very first
+    // tool call after an IDE restart doesn't false-positive the hint
+    // when `dir` wasn't passed and `lastInitializedDir` is empty (the
+    // session's not warmed up yet).
+    const anyInitialized = candidates.some((d) => isProjectInitialized(d)) ||
+        candidates.some((d) => wasInitialisedAtPath(d));
+    if (!anyInitialized) {
         head.push({ type: "text", text: INIT_HINT });
     }
     const result = [...head, ...withUpdate];
@@ -305,6 +402,42 @@ function withInitHint(content, dir) {
     return result;
 }
 const TOOL_BOOTSTRAP = "[CodeLoop] You MUST call codeloop_verify after every code change. If .codeloop/config.json is missing, call codeloop_init_project FIRST.\n\n";
+/**
+ * Zod preprocessor for `target_type` that accepts common synonyms.
+ *
+ * Photometry-DB E2E 8 regression: the agent (reasonably) tried
+ * `target_type: "windows_desktop"` because the project is a WPF
+ * Windows app, and got a hard schema-validation rejection. Same
+ * pattern for `mac_desktop`, `linux_desktop`, `web`, `android`,
+ * `ios`. Coerce them to the canonical 4-value enum so the agent
+ * isn't blocked by a thin naming convention.
+ */
+const TARGET_TYPE_SYNONYMS = {
+    desktop: "desktop",
+    windows_desktop: "desktop",
+    win_desktop: "desktop",
+    win32_desktop: "desktop",
+    mac_desktop: "desktop",
+    macos_desktop: "desktop",
+    osx_desktop: "desktop",
+    linux_desktop: "desktop",
+    native_desktop: "desktop",
+    browser: "browser",
+    web: "browser",
+    webapp: "browser",
+    chrome: "browser",
+    android_emulator: "android_emulator",
+    android: "android_emulator",
+    ios_simulator: "ios_simulator",
+    ios: "ios_simulator",
+};
+function normalizeTargetType(v) {
+    if (typeof v !== "string")
+        return v;
+    const key = v.toLowerCase().trim();
+    return TARGET_TYPE_SYNONYMS[key] ?? v;
+}
+const targetTypeSchema = z.preprocess(normalizeTargetType, z.enum(["desktop", "browser", "android_emulator", "ios_simulator"]));
 // ── Implemented Tools ────────────────────────────────────────────
 server.tool("codeloop_verify", TOOL_BOOTSTRAP + `Run the CodeLoop verification suite on the current project. Use this tool when:
 - You have implemented or modified code and need to check if it works correctly
@@ -1129,15 +1262,34 @@ Returns: confirmation + the captured image as an MCP ImageContent block so you c
         // agent forgot app_name — and the auto-fix loop would then
         // burn cycles trying to "fix design diffs" against a
         // screenshot of the editor.
-        const { detectPlatform } = await import("./tools/verify.js");
         const { loadConfig } = await import("./config.js");
-        const platform = detectPlatform(cwd);
-        const isDesktopAppProject = platform === "dotnet" || platform === "xcode" || platform === "android";
+        const { isDesktopAppProject } = await import("./tools/desktop_app_mode.js");
+        const desktopApp = isDesktopAppProject(cwd);
         const cfg = loadConfig(cwd);
         const targetApp = params.app_name ?? cfg.evidence?.target_app;
-        const result = await captureScreenshot(screenshotsDir, params.screen_name, targetApp, undefined, { desktopAppMode: isDesktopAppProject });
+        const result = await captureScreenshot(screenshotsDir, params.screen_name, targetApp, undefined, { desktopAppMode: desktopApp });
+        // Photometry-DB E2E 8 follow-on: when we capture a desktop app
+        // window, also resolve its on-screen bounds so the agent can
+        // (a) compute window-relative coords from the returned image
+        //     dimensions, and
+        // (b) pass coords:"window" to codeloop_interact to get them
+        //     translated to screen-absolute automatically.
+        // Without this, agents reasoned from a downscaled vision view
+        // of the image and clicked tens or hundreds of pixels off the
+        // intended target.
+        let windowBounds = null;
+        if (desktopApp && targetApp && result.captured) {
+            try {
+                const wm = await import("./runners/window_manager.js");
+                const b = await wm.getWindowBounds(targetApp);
+                if (b && b.width > 0 && b.height > 0) {
+                    windowBounds = { x: b.x, y: b.y, width: b.width, height: b.height };
+                }
+            }
+            catch { /* best-effort */ }
+        }
         await trackUsage(apiKey, "visual_review");
-        return result;
+        return { ...result, windowBounds };
     }, { tool: "codeloop_capture_screenshot", cwd: (params.project_dir || params.workspace_root || projectDir), input: params });
     if (typeof authResult === "object" && authResult !== null && "error" in authResult) {
         return { content: [{ type: "text", text: JSON.stringify(authResult, null, 2) }] };
@@ -1145,12 +1297,18 @@ Returns: confirmation + the captured image as an MCP ImageContent block so you c
     const result = authResult;
     const content = [];
     if (result.captured && result.paths.length > 0) {
-        content.push({ type: "text", text: JSON.stringify({
-                captured: true,
-                screen_name: params.screen_name,
-                path: result.paths[0],
-                method: result.method,
-            }, null, 2) });
+        const payload = {
+            captured: true,
+            screen_name: params.screen_name,
+            path: result.paths[0],
+            method: result.method,
+        };
+        if (result.windowBounds) {
+            payload.window_bounds = result.windowBounds;
+            payload.coordinate_hint =
+                "This screenshot captures the named window. When you compute click coordinates from the image, pass them to codeloop_interact with `coords: \"window\"` so they're translated to screen-absolute automatically. (Default `coords: \"auto\"` also works when the coord fits inside the window — but `\"window\"` is unambiguous.)";
+        }
+        content.push({ type: "text", text: JSON.stringify(payload, null, 2) });
         const data = readImageAsBase64(result.paths[0]);
         if (data) {
             content.push({ type: "image", data, mimeType: mimeForPath(result.paths[0]) });
@@ -1321,6 +1479,45 @@ After recording, call codeloop_interaction_replay to extract frames and analyze
         content: withInitHint([{ type: "text", text: JSON.stringify(result, null, 2) }]),
     };
 });
+server.tool("codeloop_launch_app", TOOL_BOOTSTRAP + `Launch a desktop application by name from a project's build output. Use when:
+- You need the app under test to be running before codeloop_start_recording / codeloop_interact.
+- The agent doesn't know where the executable lives and shouldn't have to hand-roll Start-Process / open -a.
+
+This tool is the canonical replacement for hand-coding PowerShell Start-Process / osascript / xdg-open
+from the agent. For Android / iOS, use codeloop_interact action="launch_app" with package_id instead.
+
+Search order on Windows:  publish/**/*.exe → bin/Release/**/*.exe → bin/Debug/**/*.exe (newest first).
+On macOS:                  publish/**/*.app → build/**/*.app → /Applications/<name>.app → open -a.
+On Linux:                  build/**/<name>  → bin/**/<name>  → dist/**/<name>.
+
+If app_name is omitted, falls back to evidence.target_app from .codeloop/config.json (auto-detected at
+init for .NET/Xcode/Android projects via detect-target-app).`, {
+    app_name: z.string().optional().describe("Window title / executable name of the app to launch. Defaults to evidence.target_app from .codeloop/config.json. Required if target_app is unset."),
+    project_dir: z.string().optional().describe("Absolute path to the project root. Defaults to CODELOOP_PROJECT_DIR / discovered project dir."),
+    workspace_root: z.string().optional().describe("[Alias for project_dir]"),
+}, async (params) => {
+    const authResult = await withAuth(async () => {
+        const wm = await import("./runners/window_manager.js");
+        const { loadConfig } = await import("./config.js");
+        const cwd = (params.project_dir || params.workspace_root || projectDir);
+        const cfg = loadConfig(cwd);
+        const appName = params.app_name || cfg.evidence?.target_app;
+        if (!appName) {
+            return {
+                launched: false,
+                reason: "No app_name provided and evidence.target_app is unset in .codeloop/config.json. Set it (e.g. \"evidence\": { \"target_app\": \"My App\" }) or pass app_name explicitly. For .NET/Xcode/Android projects, codeloop_init_project auto-detects this — re-run init or edit the config by hand.",
+            };
+        }
+        const r = await wm.launchDesktopApp(appName, cwd);
+        return { app_name: appName, ...r };
+    }, { tool: "codeloop_launch_app", cwd: (params.project_dir || params.workspace_root || projectDir), input: params });
+    if (typeof authResult === "object" && authResult !== null && "error" in authResult) {
+        return { content: [{ type: "text", text: JSON.stringify(authResult, null, 2) }] };
+    }
+    return {
+        content: withInitHint([{ type: "text", text: JSON.stringify(authResult, null, 2) }], params.project_dir || params.workspace_root),
+    };
+});
 server.tool("codeloop_start_recording", TOOL_BOOTSTRAP + `Start recording the app window in the background. The app is brought to the front automatically
 (un-minimized if needed). Recording continues while you interact with the app. Call codeloop_stop_recording when done.
 This is the PREFERRED recording method because it lets you actively operate the app during capture.
@@ -1347,11 +1544,12 @@ Flow: start_recording → codeloop_interact with ALL app elements → stop_recor
 Supports desktop apps, Android emulator, iOS Simulator, and browser targets.
 Multi-monitor: on macOS, automatically detects which screen the app window is on.
 App logs (stdout, logcat, simctl log) are automatically captured alongside the video.`, {
-    app_name: z.string().describe("The name of the app to record (used to find and focus its window)"),
+    app_name: z.string().optional().describe("The name of the app to record (used to find and focus its window). For desktop projects, defaults to evidence.target_app from .codeloop/config.json — set during init via detect-target-app for .NET/Xcode/Android projects, or settable manually."),
     run_id: z.string().optional().describe("Existing run ID to store the video in"),
     max_duration_seconds: z.number().default(120).describe("Safety timeout — recording stops automatically after this many seconds"),
-    target_type: z.enum(["desktop", "android_emulator", "ios_simulator", "browser"]).optional()
+    target_type: targetTypeSchema.optional()
         .describe("Capture method. Auto-detected from project if omitted. desktop=ffmpeg screen, android_emulator=adb screenrecord, ios_simulator=simctl recordVideo, browser=ffmpeg/Playwright"),
+    auto_launch: z.boolean().default(true).describe("When target_type=desktop and the app isn't already running, auto-launch it from the project's build output via evidence.target_app. Set false to skip (e.g. when the app is started by another process)."),
     project_dir: z.string().optional().describe("Absolute path to the project root. Defaults to CODELOOP_PROJECT_DIR env var or auto-discovered project directory. MUST be an actual project folder — passing the user's home directory is rejected. If your IDE launches the MCP server from the wrong cwd (common on Windows where Cursor uses C:\\Users\\<name> as cwd), set CODELOOP_PROJECT_DIR or pass this param explicitly."),
     workspace_root: z.string().optional().describe("[Alias for project_dir] Same semantics; accepted because many agents reach for this conventional name. Pass either `project_dir` OR `workspace_root` — they're equivalent."),
 }, async (params) => {
@@ -1359,6 +1557,7 @@ App logs (stdout, logcat, simctl log) are automatically captured alongside the v
         const { startBackgroundRecording } = await import("./runners/video_recorder.js");
         const { createRunDir, getRunDir, getArtifactsBaseDir } = await import("./evidence/artifacts.js");
         const { detectTargetType } = await import("./runners/platform_detect.js");
+        const { loadConfig } = await import("./config.js");
         const cwd = (params.project_dir || params.workspace_root || projectDir);
         let videosDir;
         if (params.run_id) {
@@ -1370,7 +1569,11 @@ App logs (stdout, logcat, simctl log) are automatically captured alongside the v
             videosDir = join(runDir, "videos");
         }
         const targetType = params.target_type || (await detectTargetType(cwd));
+        const cfg = loadConfig(cwd);
         let appName = params.app_name;
+        if (!appName && (targetType === "desktop")) {
+            appName = cfg.evidence?.target_app;
+        }
         if (targetType === "browser") {
             const bi = await import("./runners/browser_interaction.js");
             await bi.ensureBrowserPage();
@@ -1379,7 +1582,42 @@ App logs (stdout, logcat, simctl log) are automatically captured alongside the v
                 appName = pwAppName;
             }
         }
-        const result = await startBackgroundRecording(videosDir, appName, params.max_duration_seconds, targetType);
+        // Photometry-DB E2E 8: agents spent many turns manually
+        // probing `Get-Process` / `Start-Process` to launch the app
+        // because nothing in CodeLoop did it for them. Now, when
+        // recording a desktop app, we auto-launch from the build
+        // output if the app isn't already running.
+        const wm = await import("./runners/window_manager.js");
+        let autoLaunchSummary;
+        if (targetType === "desktop" && params.auto_launch !== false && appName) {
+            try {
+                const bounds = await wm.getWindowBounds(appName);
+                if (!bounds) {
+                    const r = await wm.launchDesktopApp(appName, cwd);
+                    autoLaunchSummary = {
+                        attempted: true,
+                        launched: r.launched,
+                        command: r.command,
+                        reason: r.reason,
+                    };
+                    if (r.launched) {
+                        // Give the window time to appear / paint before the
+                        // recorder starts capturing frames.
+                        await new Promise((res) => setTimeout(res, 2000));
+                    }
+                }
+                else {
+                    autoLaunchSummary = { attempted: false, launched: true, reason: "already running" };
+                }
+            }
+            catch (e) {
+                autoLaunchSummary = { attempted: true, launched: false, reason: e.message };
+            }
+        }
+        const result = await startBackgroundRecording(videosDir, appName ?? "", params.max_duration_seconds, targetType);
+        if (autoLaunchSummary) {
+            result.auto_launch = autoLaunchSummary;
+        }
         await trackUsage(apiKey, "visual_review");
         return result;
     }, { tool: "codeloop_start_recording", cwd: (params.project_dir || params.workspace_root || projectDir), input: params });
@@ -1829,10 +2067,25 @@ Returns: checklist of completed and pending verification steps.`, {
                 const verdict = evaluateDepth(coverage, minimums, discoverySnapshot);
                 const b = coverage.buckets;
                 const breakdown = `click=${b.click}, navigation=${b.navigation}, input=${b.input}, commit=${b.commit}, toggle=${b.toggle}, gesture=${b.gesture}, upload=${b.upload}, keystroke=${b.keystroke}, inspect=${b.inspect}`;
+                // 0.1.49: coordinate_clicks_without_intent is now a HARD
+                // step-7 PENDING blocker so the agent sees the gap BEFORE
+                // gate_check, not after. Pre-0.1.49 this only surfaced as
+                // a verify postscript note, which agents commonly ignored
+                // until the user_journey_evidence gate failed at the
+                // bottom of a long verify→capture→video→gate cycle —
+                // wasting the entire UI-evidence loop.
+                const coordsWithoutIntent = coverage.coordinate_clicks_without_intent;
                 if (!minimums.enabled) {
                     depthStatus = "n/a";
                     depthDetail = `Depth gate disabled in .codeloop/config.json. Observed buckets: ${breakdown}.`;
                 }
+                else if (coordsWithoutIntent > 0) {
+                    depthStatus = "PENDING";
+                    depthDetail =
+                        `${coverage.successful} successful interactions across ${runs.length} run(s) (${breakdown}). ` +
+                            `BLOCKER: ${coordsWithoutIntent} coordinate-only click(s) dispatched without intent / description / purpose / step fields — the CRUD classifier in user_journey_evidence cannot credit them as edit/delete/create. ` +
+                            `Re-run codeloop_interact for those clicks WITH \`intent\` (e.g. intent="confirm delete dialog", intent="save form"). Otherwise gate_check will return continue_fixing on user_journey_evidence even after the rest of the workflow is green.`;
+                }
                 else if (verdict.passed) {
                     depthStatus = "done";
                     depthDetail = `${coverage.successful} successful interactions across ${runs.length} run(s) (${breakdown}). Depth minimums met.`;
@@ -1955,8 +2208,8 @@ MANDATORY for web apps: You MUST type into form fields, fill login/signup forms,
 validation errors, and click submit buttons. Just navigating pages is NOT enough.
 Wait 1-2 seconds between interactions so video frames capture state changes.`, {
     action: z.string().describe("Action to perform: click, double_click, right_click, hover, type, keystroke, hotkey, scroll, drag_drop, long_press, type_and_submit, type_and_tab, fill_form, select_option, toggle, upload_file, navigate_url, navigate_back, navigate_forward, wait, sequence, swipe, back_button, home_button, deep_link, grant_permission, rotate_device, biometric_auth, launch_app, clear_app_data, mock_location, simulate_network, maestro_flow, win_ui_inspect, win_ui_automate"),
-    target_type: z.enum(["desktop", "browser", "android_emulator", "ios_simulator"]).optional()
-        .describe("Interaction target. Auto-detected if omitted."),
+    target_type: targetTypeSchema.optional()
+        .describe("Interaction target. Auto-detected if omitted. Accepts synonyms: `windows_desktop`/`mac_desktop`/`linux_desktop` → `desktop`; `web` → `browser`; `android` → `android_emulator`; `ios` → `ios_simulator`."),
     x: z.number().optional().describe("X coordinate for click/scroll/drag/swipe"),
     y: z.number().optional().describe("Y coordinate for click/scroll/drag/swipe"),
     x2: z.number().optional().describe("End X for drag_drop/swipe"),
@@ -1987,7 +2240,7 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
         action: z.string(),
         params: z.record(z.unknown()).optional(),
         delay_ms: z.number().optional(),
-    })).optional().describe("Steps for sequence action"),
+    }).passthrough()).optional().describe("Steps for sequence action. Accepts BOTH nested form `{ action, params: { x, y, … }, delay_ms? }` and flat form `{ action, x, y, … }` — the flat form is what agents naturally write (mirrors the top-level codeloop_interact shape). Supports inside desktop sequences: click, double_click, right_click, hover, scroll, type, hotkey, keystroke, navigate_url, wait, win_ui_automate."),
     maestro_steps: z.array(z.string()).optional().describe("High-level steps for maestro_flow"),
     automation_action: z.enum(["invoke", "setValue", "toggle", "select", "scroll"]).optional()
         .describe("For win_ui_automate"),
@@ -1997,6 +2250,8 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
     description: z.string().optional().describe("[Alias for intent] Same semantics."),
     purpose: z.string().optional().describe("[Alias for intent] Same semantics."),
     step: z.string().optional().describe("Plan-step name when this interaction is driving a codeloop_plan_user_journey arc (e.g. 'edit', 'delete', 'create', 'save', 'verify'). Logged alongside `intent` and read by the CRUD classifier."),
+    coords: z.enum(["auto", "window", "screen", "screenshot"]).optional().describe("How to interpret x/y for desktop click/double_click/right_click/hover/scroll/drag/long_press. `auto` (default): if `app_name` resolves to a visible window AND (x, y) fits inside the window's client area, treat as window-relative and auto-offset by the window origin; otherwise leave as raw screen-absolute coords. `window`: ALWAYS add the window origin offset (errors if the window isn't found). `screen`: ALWAYS pass through (legacy behaviour, matches CGEvent / user32.dll / xdotool semantics). `screenshot` (most accurate for vision-driven agents): treat (x, y) as coordinates against a captured screenshot — provide `screenshot_path` so the runner can read the image's actual width/height, scale (x, y) to the window's true pixel dimensions, then add the window origin and apply DPI. Use this whenever you computed coords from the image returned by codeloop_capture_screenshot, especially when the MCP transport may have downscaled the PNG. Fixes the Photometry-DB E2E 8 failure mode where the agent captured a 1600×900 window screenshot, computed click coords against the image, and missed the sidebar because the window's actual top-left was (286, 286) on a 5120×1440 screen."),
+    screenshot_path: z.string().optional().describe("Absolute path to the screenshot PNG that x/y were computed against. Used with `coords: \"screenshot\"` to scale agent-supplied coords from the captured image dimensions to the window's actual pixel dimensions before applying the window origin and DPI factor. Pass the `path` field returned by codeloop_capture_screenshot."),
     project_dir: z.string().optional().describe("Absolute path to project root."),
     workspace_root: z.string().optional().describe("[Alias for project_dir] Pass either; they're equivalent."),
 }, async (params) => {
@@ -2026,13 +2281,108 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
             await bi.ensureBrowserPage();
         }
         // Bring the app to front before desktop interactions (non-browser, non-mobile).
+        let windowOriginOffset = null;
+        let screenshotDims = null;
         if (tt === "desktop") {
             const appName = params.app_name || vr.getActiveRecordingAppName();
             if (appName && action !== "wait") {
                 await wm.bringAppToFront(appName);
                 await new Promise(r => setTimeout(r, 300));
+                // Photometry-DB E2E 8: agents commonly compute click coords
+                // from a window-cropped screenshot (which is what
+                // codeloop_capture_screenshot returns when `app_name` is
+                // set), then pass those coords to codeloop_interact —
+                // which expects raw SCREEN coordinates. On a multi-monitor
+                // / DPI-scaled setup that mismatch silently dropped clicks
+                // 100s of pixels off-target. When `coords` is `auto` (the
+                // default) we look up the window's actual screen origin
+                // and add it to x/y, but ONLY if (x, y) fits inside the
+                // window — that keeps legacy callers passing raw screen
+                // coords working unchanged. `coords: "window"` forces the
+                // offset; `coords: "screen"` opts out.
+                const coordsMode = params.coords ?? "auto";
+                if (coordsMode !== "screen") {
+                    try {
+                        const b = await wm.getWindowBounds(appName);
+                        if (b && b.width > 0 && b.height > 0) {
+                            windowOriginOffset = {
+                                dx: b.x,
+                                dy: b.y,
+                                width: b.width,
+                                height: b.height,
+                                dpiX: b.dpi_x,
+                                dpiY: b.dpi_y,
+                            };
+                        }
+                    }
+                    catch { /* best-effort */ }
+                }
+                // For coords:"screenshot", load the actual PNG dims so we
+                // can scale agent-supplied (x, y) up from the (possibly
+                // MCP-downscaled) image to the window's true pixel size.
+                if (coordsMode === "screenshot" && params.screenshot_path) {
+                    try {
+                        const { readPngDims } = await import("./runners/png_dims.js");
+                        screenshotDims = readPngDims(params.screenshot_path);
+                    }
+                    catch { /* best-effort */ }
+                }
             }
         }
+        // Helper used by every coordinate-driven desktop action below.
+        // Photometry-DB E2E 8 + 0.1.49 hardening: handles four modes
+        // (auto / window / screen / screenshot) plus an optional DPI
+        // factor on the window bounds so high-DPI Windows / Retina
+        // displays don't drop clicks 100s of pixels off-target.
+        const translateXY = (x, y) => {
+            if (tt !== "desktop" || x == null || y == null || !windowOriginOffset) {
+                return { x, y };
+            }
+            const mode = params.coords ?? "auto";
+            if (mode === "screen")
+                return { x, y };
+            const applyDpi = (px, py) => {
+                // window_manager records DPI in physical-pixel-per-logical
+                // form (1.0 = 96 DPI baseline; 2.0 = 200% / Retina). When
+                // the screenshot was captured in logical pixels but the
+                // OS click API expects physical pixels (Win32 user32.dll
+                // and modern macOS CGEvent both expect physical), scale up.
+                const dpiX = windowOriginOffset.dpiX ?? 1;
+                const dpiY = windowOriginOffset.dpiY ?? 1;
+                if (dpiX === 1 && dpiY === 1)
+                    return { x: px, y: py };
+                return { x: px * dpiX, y: py * dpiY };
+            };
+            if (mode === "screenshot") {
+                // Scale (x, y) from screenshot dims → window dims,
+                // then add the window origin, then DPI.
+                let sx = x;
+                let sy = y;
+                if (screenshotDims && screenshotDims.width > 0 && screenshotDims.height > 0) {
+                    const ratioX = windowOriginOffset.width / screenshotDims.width;
+                    const ratioY = windowOriginOffset.height / screenshotDims.height;
+                    sx = x * ratioX;
+                    sy = y * ratioY;
+                }
+                const dpi = applyDpi(sx, sy);
+                return { x: dpi.x + windowOriginOffset.dx, y: dpi.y + windowOriginOffset.dy };
+            }
+            if (mode === "window") {
+                const dpi = applyDpi(x, y);
+                return { x: dpi.x + windowOriginOffset.dx, y: dpi.y + windowOriginOffset.dy };
+            }
+            // auto: if (x, y) fits inside the window's client area,
+            // assume the agent computed against a window-cropped
+            // screenshot and add the origin. Otherwise pass through
+            // (likely a raw screen coord from a manual workflow).
+            const inside = x >= 0 && x <= windowOriginOffset.width &&
+                y >= 0 && y <= windowOriginOffset.height;
+            if (inside) {
+                const dpi = applyDpi(x, y);
+                return { x: dpi.x + windowOriginOffset.dx, y: dpi.y + windowOriginOffset.dy };
+            }
+            return { x, y };
+        };
         switch (action) {
             case "click":
                 if (tt === "browser" && params.selector) {
@@ -2054,7 +2404,8 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                     }
                 }
                 else if (params.x != null && params.y != null) {
-                    success = await wm.clickAtPosition(params.x, params.y);
+                    const t = translateXY(params.x, params.y);
+                    success = await wm.clickAtPosition(t.x, t.y);
                 }
                 detail = `click at ${params.selector || `(${params.x},${params.y})`}`;
                 break;
@@ -2063,7 +2414,8 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                     success = await bi.browserDoubleClick(params.selector);
                 }
                 else if (params.x != null && params.y != null) {
-                    success = await wm.doubleClickAtPosition(params.x, params.y);
+                    const t = translateXY(params.x, params.y);
+                    success = await wm.doubleClickAtPosition(t.x, t.y);
                 }
                 detail = `double_click at ${params.selector || `(${params.x},${params.y})`}`;
                 break;
@@ -2072,7 +2424,8 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                     success = await bi.browserRightClick(params.selector);
                 }
                 else if (params.x != null && params.y != null) {
-                    success = await wm.rightClickAtPosition(params.x, params.y);
+                    const t = translateXY(params.x, params.y);
+                    success = await wm.rightClickAtPosition(t.x, t.y);
                 }
                 detail = `right_click at ${params.selector || `(${params.x},${params.y})`}`;
                 break;
@@ -2081,7 +2434,8 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                     success = await bi.browserHover(params.selector);
                 }
                 else if (params.x != null && params.y != null) {
-                    success = await wm.hoverAtPosition(params.x, params.y);
+                    const t = translateXY(params.x, params.y);
+                    success = await wm.hoverAtPosition(t.x, t.y);
                 }
                 detail = `hover at ${params.selector || `(${params.x},${params.y})`}`;
                 break;
@@ -2166,7 +2520,8 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                     success = await wm.simctlSwipe(sx, sy, ex, ey);
                 }
                 else {
-                    success = await wm.scrollAtPosition(params.x || 500, params.y || 400, params.direction || "down", params.amount || 3);
+                    const t = translateXY(params.x || 500, params.y || 400);
+                    success = await wm.scrollAtPosition(t.x, t.y, params.direction || "down", params.amount || 3);
                 }
                 detail = `scroll ${params.direction || "down"}`;
                 break;
@@ -2179,7 +2534,9 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                         success = await wm.adbSwipe(params.x, params.y, params.x2, params.y2, params.duration_ms || 500);
                     }
                     else {
-                        success = await wm.dragDrop(params.x, params.y, params.x2, params.y2, params.duration_ms || 500);
+                        const a = translateXY(params.x, params.y);
+                        const b = translateXY(params.x2, params.y2);
+                        success = await wm.dragDrop(a.x, a.y, b.x, b.y, params.duration_ms || 500);
                     }
                 }
                 detail = `drag_drop`;
@@ -2189,7 +2546,8 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                     success = await wm.adbLongPress(params.x, params.y, params.duration_ms || 1000);
                 }
                 else if (params.x != null && params.y != null) {
-                    success = await wm.longPressAtPosition(params.x, params.y, params.duration_ms || 1000);
+                    const t = translateXY(params.x, params.y);
+                    success = await wm.longPressAtPosition(t.x, t.y, params.duration_ms || 1000);
                 }
                 detail = `long_press at (${params.x},${params.y})`;
                 break;
@@ -2371,11 +2729,37 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                 if (tt === "android_emulator" && params.package_id) {
                     const r = await import("./runners/base.js").then(m => m.runCommand("adb", ["shell", "am", "start", "-n", params.package_id], process.cwd()));
                     success = r.exit_code === 0;
+                    detail = `launch_app "${params.package_id}"`;
                 }
                 else if (tt === "ios_simulator" && params.package_id) {
                     success = await wm.simctlLaunch(params.package_id);
+                    detail = `launch_app "${params.package_id}"`;
+                }
+                else if (tt === "desktop") {
+                    // Photometry-DB E2E 8: desktop launch was completely
+                    // missing — agents had to hand-roll PowerShell
+                    // Start-Process / `open -a` calls. Now resolves via
+                    // evidence.target_app from the project config when
+                    // app_name is omitted.
+                    const { loadConfig } = await import("./config.js");
+                    const cfg = loadConfig(cwd);
+                    const appName = params.app_name || cfg.evidence?.target_app;
+                    if (!appName) {
+                        success = false;
+                        detail = "launch_app desktop: no app_name provided and evidence.target_app is unset in .codeloop/config.json. Set it (e.g. \"target_app\": \"Photometry DB\") or pass app_name explicitly.";
+                    }
+                    else {
+                        const r = await wm.launchDesktopApp(appName, cwd);
+                        success = r.launched;
+                        detail = r.launched
+                            ? `launch_app "${appName}" via ${r.command}${r.pid ? ` (pid ${r.pid})` : ""}`
+                            : `launch_app "${appName}" failed: ${r.reason || "unknown error"}`;
+                    }
+                }
+                else {
+                    success = false;
+                    detail = `launch_app "${params.package_id || params.app_name || ""}": target ${tt} not supported in this action`;
                 }
-                detail = `launch_app "${params.package_id}"`;
                 break;
             case "clear_app_data":
                 if (tt === "android_emulator" && params.package_id) {
@@ -2439,7 +2823,22 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                         if (step.delay_ms)
                             await new Promise(r => setTimeout(r, step.delay_ms));
                         const stepAction = step.action;
-                        const sp = (step.params || {});
+                        // Photometry-DB E2E 8: agents naturally write steps in
+                        // FLAT form `{ action, x, y, ms, … }` because that
+                        // mirrors the top-level codeloop_interact shape. The
+                        // schema documented the NESTED form `{ action,
+                        // params: { … } }`. Now we accept both: prefer
+                        // `step.params` if present, otherwise fall back to the
+                        // step object itself minus the wrapper keys.
+                        const stepObj = step;
+                        const nested = (step.params || {});
+                        const sp = Object.keys(nested).length > 0
+                            ? nested
+                            : Object.fromEntries(Object.entries(stepObj).filter(([k]) => k !== "action" && k !== "params" && k !== "delay_ms"));
+                        // Convenient aliases: agents wrote `ms` for wait
+                        // duration in the log; accept that as `duration_ms`.
+                        if (sp.ms != null && sp.duration_ms == null)
+                            sp.duration_ms = sp.ms;
                         let stepOk = false;
                         let stepReason;
                         try {
@@ -2447,7 +2846,20 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                                 stepOk = await bi.browserClick(sp.selector);
                             }
                             else if (stepAction === "click" && sp.x != null && sp.y != null) {
-                                stepOk = await wm.clickAtPosition(sp.x, sp.y);
+                                const t = translateXY(sp.x, sp.y);
+                                stepOk = await wm.clickAtPosition(t.x, t.y);
+                            }
+                            else if (stepAction === "double_click" && tt !== "browser" && sp.x != null && sp.y != null) {
+                                const t = translateXY(sp.x, sp.y);
+                                stepOk = await wm.doubleClickAtPosition(t.x, t.y);
+                            }
+                            else if (stepAction === "right_click" && tt !== "browser" && sp.x != null && sp.y != null) {
+                                const t = translateXY(sp.x, sp.y);
+                                stepOk = await wm.rightClickAtPosition(t.x, t.y);
+                            }
+                            else if (stepAction === "hover" && tt !== "browser" && sp.x != null && sp.y != null) {
+                                const t = translateXY(sp.x, sp.y);
+                                stepOk = await wm.hoverAtPosition(t.x, t.y);
                             }
                             else if (stepAction === "type" && tt === "browser" && sp.selector && sp.text) {
                                 stepOk = await bi.browserType(sp.selector, sp.text);
@@ -2483,9 +2895,13 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                                 stepOk = tt === "browser" ? await bi.browserKeystroke(sp.key) : await wm.sendKeyByName(sp.key);
                             }
                             else if (stepAction === "scroll") {
-                                stepOk = tt === "browser"
-                                    ? await bi.browserScroll(sp.direction || "down", sp.amount || 300)
-                                    : await wm.scrollAtPosition(sp.x || 500, sp.y || 400, sp.direction || "down", sp.amount || 3);
+                                if (tt === "browser") {
+                                    stepOk = await bi.browserScroll(sp.direction || "down", sp.amount || 300);
+                                }
+                                else {
+                                    const t = translateXY(sp.x || 500, sp.y || 400);
+                                    stepOk = await wm.scrollAtPosition(t.x, t.y, sp.direction || "down", sp.amount || 3);
+                                }
                             }
                             else if (stepAction === "wait") {
                                 await new Promise(r => setTimeout(r, sp.duration_ms || 1000));
@@ -2818,6 +3234,42 @@ No project_dir / workspace_root required — this tool is workspace-independent.
         ]),
     };
 });
+server.tool("codeloop_self_test", TOOL_BOOTSTRAP + `Pre-flight smoke test for CodeLoop on the current workspace. Run this on any NEW project BEFORE your first verify cycle, or whenever something looks off (silent IDE captures, "no .exe found", design_compare returning 0%, etc.).
+
+It validates every critical pre-condition synthetically (no live build, no live screenshot, no network past the platform sniff):
+- Workspace exists on disk and is a directory
+- codeloop_init_project has been run (.codeloop/config.json present)
+- Platform detection produced a known platform
+- isDesktopAppProject correctly identifies the project type (so captureScreenshot won't silently fall back to fullscreen)
+- evidence.target_app is set when desktop-app mode is ON (so launchDesktopApp + captureScreenshot can resolve a window)
+- PNG decoder skip path is wired (corrupt PNGs become skip warnings, not 0% match)
+- Coordinate translation round-trips on a synthetic high-DPI fixture (so clicks land where the agent expects on Retina / 200%-DPI displays)
+
+Returns a structured pass/fail report with per-check fix suggestions and a single \`next_step\` directive.
+
+Use this tool FIRST when:
+- The user reports CodeLoop "isn't working" or evidence is missing
+- Switching to a project / repo you've never run CodeLoop against
+- Debugging unexplained gate failures that don't match the agent's mental model
+
+Idempotent and free — safe to call as the first step of every new chat.`, {
+    project_dir: z.string().optional().describe("Absolute path to the project root. Defaults to CODELOOP_PROJECT_DIR env var or auto-discovered project directory."),
+    workspace_root: z.string().optional().describe("[Alias for project_dir] Same semantics."),
+}, async (params) => {
+    const result = await withAuth(async () => {
+        const cwd = (params.project_dir || params.workspace_root || projectDir);
+        const { runSelfTest } = await import("./tools/self_test.js");
+        return runSelfTest(cwd);
+    }, { tool: "codeloop_self_test", cwd: (params.project_dir || params.workspace_root || projectDir), input: params });
+    if (typeof result === "object" && result !== null && "error" in result) {
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    return {
+        content: withInitHint([
+            { type: "text", text: JSON.stringify(result, null, 2) },
+        ]),
+    };
+});
 server.tool("codeloop_apply_update", TOOL_BOOTSTRAP + `Apply a pending CodeLoop MCP server update to the current chat session — without asking the user to restart their IDE.
 
 Use this tool when: