codeloop-mcp-server 0.1.48 → 0.1.50

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,11 +20,13 @@ 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";
 import { isLocalMode } from "./auth/local_mode.js";
 import { discoverProjectDir } from "./project-discovery.js";
+import { resolveProjectDirPath } from "./runners/resolve_project_dir.js";
 function readImageAsBase64(path) {
     if (!existsSync(path))
         return null;
@@ -60,6 +62,18 @@ function mimeForPath(path) {
 //     when the server's auto-discovered fallback is uninitialized.
 const discovery = discoverProjectDir();
 const projectDir = discovery.projectDir;
+// 0.1.50 H4 — single helper that applies the project_dir precedence
+// ladder (explicit > workspace_root > active recording > env > walked_up
+// > default). Used by every capture / interact / record / replay / etc
+// handler so we can't drift back to the Photometry-DB regression where
+// missing project_dir wrote artifacts to the user's HOME folder.
+function resolveCwd(params) {
+    return resolveProjectDirPath({
+        project_dir: params.project_dir,
+        workspace_root: params.workspace_root,
+        default_dir: projectDir,
+    });
+}
 if (discovery.source !== "cwd" && discovery.source !== "env") {
     console.error(`[CodeLoop] Auto-discovered project at: ${projectDir} (via ${discovery.source} search)`);
 }
@@ -87,6 +101,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
@@ -310,6 +367,13 @@ function rememberInitializedDir(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) {
@@ -336,7 +400,12 @@ function withInitHint(content, dir) {
     //      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);
-    const anyInitialized = candidates.some((d) => isProjectInitialized(d));
+    // 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 });
     }
@@ -400,7 +469,7 @@ Returns: structured report with pass/fail counts, artifact paths, and next-step
     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) => {
-    const cwd = (params.project_dir || params.workspace_root || projectDir);
+    const cwd = resolveCwd(params);
     const explicitDir = params.project_dir || params.workspace_root;
     const cfg = explicitDir ? loadConfig(explicitDir) : config;
     const result = await withAuth(async () => {
@@ -488,11 +557,11 @@ Returns: categorized issues with severity, evidence, root cause, and actionable
             run_id: params.run_id,
             focus_files: params.focus_files,
         };
-        const cwd = (params.project_dir || params.workspace_root || projectDir);
+        const cwd = resolveCwd(params);
         const output = await runDiagnose(input, config, cwd);
         await trackUsage(apiKey, "verification_run");
         return output;
-    }, { tool: "codeloop_diagnose", cwd: (params.project_dir || params.workspace_root || projectDir), input: params });
+    }, { tool: "codeloop_diagnose", cwd: resolveCwd(params), input: params });
     // Auto-fix-loop directive. Diagnose is only useful when it leads
     // to a fix + re-verify, not when it leads to a long deliberation
     // over which repair to do first. The repair_tasks array in the
@@ -556,7 +625,7 @@ Returns: pass/fail for each gate, overall confidence score, and recommendation.`
             spec_path: params.spec_path,
             acceptance_path: params.acceptance_path,
         };
-        const cwd = (params.project_dir || params.workspace_root || projectDir);
+        const cwd = resolveCwd(params);
         const output = await runGateCheck(input, config, cwd);
         // Persist gate_result and confidence to meta.json
         try {
@@ -576,7 +645,7 @@ Returns: pass/fail for each gate, overall confidence score, and recommendation.`
         catch { /* best-effort persistence */ }
         await trackUsage(apiKey, "verification_run");
         return output;
-    }, { tool: "codeloop_gate_check", cwd: (params.project_dir || params.workspace_root || projectDir), input: params });
+    }, { tool: "codeloop_gate_check", cwd: resolveCwd(params), input: params });
     const resultJson = JSON.stringify(result, null, 2);
     const gateResult = result;
     if (gateResult.recommendation === "continue_fixing") {
@@ -634,11 +703,11 @@ Returns: pass/fail for each gate, overall confidence score, and recommendation.`
             "INCOMPLETE CRUD ARC is NEVER a reason to stop — call codeloop_plan_user_journey, follow the returned per-entity script, re-record, THEN re-gate.",
         ].join("\n");
         return {
-            content: withInitHint([{ type: "text", text: resultJson + loopDirective }], (params.project_dir || params.workspace_root || projectDir)),
+            content: withInitHint([{ type: "text", text: resultJson + loopDirective }], resolveCwd(params)),
         };
     }
     return {
-        content: withInitHint([{ type: "text", text: resultJson }], (params.project_dir || params.workspace_root || projectDir)),
+        content: withInitHint([{ type: "text", text: resultJson }], resolveCwd(params)),
     };
 });
 // ── Vision Tools (agent-delegated: returns images for AI agent analysis) ──
@@ -665,11 +734,11 @@ Returns: deterministic diff results + screenshot images for visual analysis.`, {
             ux_checklist_path: params.ux_checklist_path,
             viewport_sizes: params.viewport_sizes,
         };
-        const cwd = (params.project_dir || params.workspace_root || projectDir);
+        const cwd = resolveCwd(params);
         const result = await runVisualReview(input, config, cwd);
         await trackUsage(apiKey, "visual_review");
         return result;
-    }, { tool: "codeloop_visual_review", cwd: (params.project_dir || params.workspace_root || projectDir), input: params });
+    }, { tool: "codeloop_visual_review", cwd: resolveCwd(params), input: params });
     if (typeof authResult === "object" && authResult !== null && "error" in authResult) {
         return { content: [{ type: "text", text: JSON.stringify(authResult, null, 2) }] };
     }
@@ -750,11 +819,11 @@ Returns: per-screen pixel diff scores + worst-failing reference, actual, and dif
             designs_dir: params.designs_dir,
             run_id: params.run_id,
         };
-        const cwd = (params.project_dir || params.workspace_root || projectDir);
+        const cwd = resolveCwd(params);
         const result = await runDesignCompare(input, config, cwd);
         await trackUsage(apiKey, "visual_review");
         return result;
-    }, { tool: "codeloop_design_compare", cwd: (params.project_dir || params.workspace_root || projectDir), input: params });
+    }, { tool: "codeloop_design_compare", cwd: resolveCwd(params), input: params });
     if (typeof authResult === "object" && authResult !== null && "error" in authResult) {
         return { content: [{ type: "text", text: JSON.stringify(authResult, null, 2) }] };
     }
@@ -1069,7 +1138,7 @@ Returns: extracted key frames as images + expected flow description + app logs f
 }, async (params) => {
     const authResult = await withAuth(async () => {
         const { runInteractionReplay } = await import("./tools/interaction_replay.js");
-        const cwd = (params.project_dir || params.workspace_root || projectDir);
+        const cwd = resolveCwd(params);
         const output = await runInteractionReplay({
             video_path: params.video_path,
             run_id: params.run_id,
@@ -1077,7 +1146,7 @@ Returns: extracted key frames as images + expected flow description + app logs f
         }, config, cwd);
         await trackUsage(apiKey, "visual_review");
         return output;
-    }, { tool: "codeloop_interaction_replay", cwd: (params.project_dir || params.workspace_root || projectDir), input: params });
+    }, { tool: "codeloop_interaction_replay", cwd: resolveCwd(params), input: params });
     if (typeof authResult === "object" && authResult !== null && "error" in authResult) {
         return { content: [{ type: "text", text: JSON.stringify(authResult, null, 2) }] };
     }
@@ -1186,7 +1255,7 @@ Returns: confirmation + the captured image as an MCP ImageContent block so you c
     const authResult = await withAuth(async () => {
         const { captureScreenshot } = await import("./runners/screenshot.js");
         const { createRunDir, getRunDir, getArtifactsBaseDir } = await import("./evidence/artifacts.js");
-        const cwd = (params.project_dir || params.workspace_root || projectDir);
+        const cwd = resolveCwd(params);
         let screenshotsDir;
         if (params.run_id) {
             const base = getArtifactsBaseDir(cwd);
@@ -1206,13 +1275,12 @@ 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
@@ -1223,7 +1291,7 @@ Returns: confirmation + the captured image as an MCP ImageContent block so you c
         // of the image and clicked tens or hundreds of pixels off the
         // intended target.
         let windowBounds = null;
-        if (isDesktopAppProject && targetApp && result.captured) {
+        if (desktopApp && targetApp && result.captured) {
             try {
                 const wm = await import("./runners/window_manager.js");
                 const b = await wm.getWindowBounds(targetApp);
@@ -1235,7 +1303,7 @@ Returns: confirmation + the captured image as an MCP ImageContent block so you c
         }
         await trackUsage(apiKey, "visual_review");
         return { ...result, windowBounds };
-    }, { tool: "codeloop_capture_screenshot", cwd: (params.project_dir || params.workspace_root || projectDir), input: params });
+    }, { tool: "codeloop_capture_screenshot", cwd: resolveCwd(params), input: params });
     if (typeof authResult === "object" && authResult !== null && "error" in authResult) {
         return { content: [{ type: "text", text: JSON.stringify(authResult, null, 2) }] };
     }
@@ -1281,8 +1349,8 @@ Returns: list of discovered screens with routes, navigation triggers, confidence
 }, async (params) => {
     const result = await withAuth(async () => {
         const { discoverScreens } = await import("./tools/discover_screens.js");
-        return discoverScreens((params.project_dir || params.workspace_root || projectDir), params.platform);
-    }, { tool: "codeloop_discover_screens", cwd: (params.project_dir || params.workspace_root || projectDir), input: params });
+        return discoverScreens(resolveCwd(params), params.platform);
+    }, { tool: "codeloop_discover_screens", cwd: resolveCwd(params), input: params });
     return {
         content: withInitHint([{ type: "text", text: JSON.stringify(result, null, 2) }]),
     };
@@ -1316,8 +1384,8 @@ selects, datagrids, upload_areas, ai_features, forms }, ai_features_detected, sc
 }, async (params) => {
     const result = await withAuth(async () => {
         const { discoverInteractions } = await import("./tools/discover_interactions.js");
-        return discoverInteractions((params.project_dir || params.workspace_root || projectDir), params.platform);
-    }, { tool: "codeloop_discover_interactions", cwd: (params.project_dir || params.workspace_root || projectDir), input: params });
+        return discoverInteractions(resolveCwd(params), params.platform);
+    }, { tool: "codeloop_discover_interactions", cwd: resolveCwd(params), input: params });
     return {
         content: withInitHint([{ type: "text", text: JSON.stringify(result, null, 2) }]),
     };
@@ -1359,8 +1427,8 @@ ai_substantive_prompts, upload_actions, datagrid_edits }, advice, discovered_int
 }, async (params) => {
     const result = await withAuth(async () => {
         const { planUserJourney } = await import("./tools/plan_user_journey.js");
-        return planUserJourney((params.project_dir || params.workspace_root || projectDir), params.platform, params.top_n);
-    }, { tool: "codeloop_plan_user_journey", cwd: (params.project_dir || params.workspace_root || projectDir), input: params });
+        return planUserJourney(resolveCwd(params), params.platform, params.top_n);
+    }, { tool: "codeloop_plan_user_journey", cwd: resolveCwd(params), input: params });
     // Auto-fix loop directive. The plan is ONLY useful if the agent
     // now drives it via a recording session — otherwise it's a
     // detailed document that gets read and then deliberated over.
@@ -1402,7 +1470,7 @@ After recording, call codeloop_interaction_replay to extract frames and analyze
     const authResult = await withAuth(async () => {
         const { recordVideo } = await import("./runners/video_recorder.js");
         const { createRunDir, getRunDir, getArtifactsBaseDir } = await import("./evidence/artifacts.js");
-        const cwd = (params.project_dir || params.workspace_root || projectDir);
+        const cwd = resolveCwd(params);
         let videosDir;
         if (params.run_id) {
             const base = getArtifactsBaseDir(cwd);
@@ -1415,7 +1483,7 @@ After recording, call codeloop_interaction_replay to extract frames and analyze
         const result = await recordVideo(videosDir, params.duration_seconds, params.app_name);
         await trackUsage(apiKey, "visual_review");
         return result;
-    }, { tool: "codeloop_record_interaction", cwd: (params.project_dir || params.workspace_root || projectDir), input: params });
+    }, { tool: "codeloop_record_interaction", cwd: resolveCwd(params), input: params });
     if (typeof authResult === "object" && authResult !== null && "error" in authResult) {
         return { content: [{ type: "text", text: JSON.stringify(authResult, null, 2) }] };
     }
@@ -1444,7 +1512,7 @@ init for .NET/Xcode/Android projects via detect-target-app).`, {
     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 cwd = resolveCwd(params);
         const cfg = loadConfig(cwd);
         const appName = params.app_name || cfg.evidence?.target_app;
         if (!appName) {
@@ -1455,7 +1523,7 @@ init for .NET/Xcode/Android projects via detect-target-app).`, {
         }
         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 });
+    }, { tool: "codeloop_launch_app", cwd: resolveCwd(params), input: params });
     if (typeof authResult === "object" && authResult !== null && "error" in authResult) {
         return { content: [{ type: "text", text: JSON.stringify(authResult, null, 2) }] };
     }
@@ -1503,7 +1571,7 @@ App logs (stdout, logcat, simctl log) are automatically captured alongside the v
         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);
+        const cwd = resolveCwd(params);
         let videosDir;
         if (params.run_id) {
             const base = getArtifactsBaseDir(cwd);
@@ -1565,7 +1633,7 @@ App logs (stdout, logcat, simctl log) are automatically captured alongside the v
         }
         await trackUsage(apiKey, "visual_review");
         return result;
-    }, { tool: "codeloop_start_recording", cwd: (params.project_dir || params.workspace_root || projectDir), input: params });
+    }, { tool: "codeloop_start_recording", cwd: resolveCwd(params), input: params });
     if (typeof authResult === "object" && authResult !== null && "error" in authResult) {
         return { content: [{ type: "text", text: JSON.stringify(authResult, null, 2) }] };
     }
@@ -1648,7 +1716,7 @@ The agent MUST then write the report to docs/DEVELOPMENT_LOG.md and present it t
     const result = await withAuth(async () => {
         const { listRuns, loadRunMeta, getArtifactsBaseDir, getRunDir } = await import("./evidence/artifacts.js");
         const { readdirSync, existsSync } = await import("fs");
-        const cwd = (params.project_dir || params.workspace_root || projectDir);
+        const cwd = resolveCwd(params);
         const baseDir = getArtifactsBaseDir(cwd);
         const runs = listRuns(baseDir);
         const runSummaries = [];
@@ -1793,7 +1861,7 @@ The agent MUST then write the report to docs/DEVELOPMENT_LOG.md and present it t
         };
         await trackUsage(apiKey, "verification_run");
         return report;
-    }, { tool: "codeloop_generate_dev_report", cwd: (params.project_dir || params.workspace_root || projectDir), input: params });
+    }, { tool: "codeloop_generate_dev_report", cwd: resolveCwd(params), input: params });
     if (typeof result === "object" && result !== null && "error" in result) {
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     }
@@ -1915,7 +1983,7 @@ Returns: checklist of completed and pending verification steps.`, {
         const { listRuns, loadRunMeta, getArtifactsBaseDir, getRunDir } = await import("./evidence/artifacts.js");
         const { detectPlatform } = await import("./tools/verify.js");
         const { detectDesktopUI } = await import("./tools/desktop_detection.js");
-        const cwd = (params.project_dir || params.workspace_root || projectDir);
+        const cwd = resolveCwd(params);
         const platform = detectPlatform(cwd);
         // UI detection includes desktop .NET / native: WPF, WinForms, MAUI,
         // Avalonia, WinUI, UWP. Without this, every WPF/.NET 8 / MAUI / Avalonia
@@ -2012,10 +2080,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.`;
@@ -2104,7 +2187,7 @@ Returns: checklist of completed and pending verification steps.`, {
                 ? "All CodeLoop verification steps are complete. You may proceed."
                 : `WARNING: ${pendingSteps.length} step(s) still pending. DO NOT declare this task complete. DO NOT ask the user what to do next. Complete the pending steps below, then call codeloop_gate_check. If gate returns continue_fixing, loop back and fix without asking.\n${pendingSteps.map(s => `  - ${s.step}: ${s.detail}`).join("\n")}`,
         };
-    }, { tool: "codeloop_check_workflow", cwd: (params.project_dir || params.workspace_root || projectDir), input: params });
+    }, { tool: "codeloop_check_workflow", cwd: resolveCwd(params), input: params });
     return {
         content: withInitHint([{ type: "text", text: JSON.stringify(result, null, 2) }]),
     };
@@ -2144,11 +2227,13 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
     y: z.number().optional().describe("Y coordinate for click/scroll/drag/swipe"),
     x2: z.number().optional().describe("End X for drag_drop/swipe"),
     y2: z.number().optional().describe("End Y for drag_drop/swipe"),
-    text: z.string().optional().describe("Text for type/type_and_submit/type_and_tab/fill"),
+    text: z.string().optional().describe("Text for type/type_and_submit/type_and_tab/fill. 0.1.50+: ALSO accepted on click/double_click/right_click/hover with no x/y on Windows desktop targets — walks the UIA tree to find the first element whose Name property matches (exact, then substring) and clicks its centre. Closes the Photometry-DB E2E 8 regression where `{ action: \"click\", text: \"Luminaire Photometric Data\" }` produced `click at (undefined, undefined)`."),
     key: z.string().optional().describe("Key name for keystroke: enter, tab, escape, backspace, delete, etc."),
     keys: z.string().optional().describe("Key combo for hotkey: cmd+s, ctrl+enter, cmd+shift+z, etc."),
     selector: z.string().optional().describe("CSS selector (browser) or automation ID (Windows)"),
     selector2: z.string().optional().describe("Second selector for drag target"),
+    automation_id: z.string().optional().describe("[Windows desktop] UIA AutomationId of the target element. 0.1.50+: when supplied for click/double_click/right_click/hover with no x/y, CodeLoop walks the UIA tree and resolves the element's screen coords automatically (DPI-aware, window-origin-aware), then clicks at the centre. Most stable selector for WPF/WinUI/UWP — prefer this over `text` whenever the control exposes one."),
+    role: z.string().optional().describe("[Windows desktop] UIA ControlType programmatic name (e.g. `ControlType.Button`, `ControlType.TabItem`). 0.1.50+: when supplied for click/double_click/right_click/hover with no x/y, walks the UIA tree and clicks the FIRST element of that ControlType. Use as a last resort when neither AutomationId nor Name is specific enough."),
     url: z.string().optional().describe("URL for navigate_url or deep_link"),
     direction: z.enum(["up", "down", "left", "right"]).optional().describe("Scroll/swipe direction"),
     amount: z.number().optional().describe("Scroll amount or other numeric value"),
@@ -2180,7 +2265,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"]).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). 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."),
+    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) => {
@@ -2193,7 +2279,7 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
         const bi = await import("./runners/browser_interaction.js");
         const vr = await import("./runners/video_recorder.js");
         // Auto-detect target_type when omitted
-        const cwd = (params.project_dir || params.workspace_root || projectDir);
+        const cwd = resolveCwd(params);
         let tt = params.target_type;
         if (!tt) {
             const recordingTarget = vr.getActiveRecordingTargetType();
@@ -2211,6 +2297,7 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
         }
         // 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") {
@@ -2233,14 +2320,68 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                     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 };
+                            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 */ }
+                }
             }
         }
+        // 0.1.50 H1 — when an agent passes `text` / `role` /
+        // `automation_id` (no x/y) to a desktop click-family action,
+        // walk the UIA tree to resolve the centre of the matching
+        // element. The resolved (x, y) is screen-absolute so it
+        // bypasses translateXY (which is for agent-supplied coords).
+        const resolveDesktopSelector = async () => {
+            if (tt !== "desktop" || process.platform !== "win32")
+                return null;
+            if (params.x != null && params.y != null)
+                return null;
+            const appName = params.app_name || vr.getActiveRecordingAppName();
+            if (!appName)
+                return null;
+            const hasSelector = (params.automation_id && params.automation_id.length > 0) ||
+                (params.text && params.text.length > 0) ||
+                (params.role && params.role.length > 0);
+            if (!hasSelector)
+                return null;
+            try {
+                const { resolveSelectorToXY } = await import("./runners/uia_resolver.js");
+                const r = await resolveSelectorToXY({
+                    appName,
+                    automationId: params.automation_id,
+                    text: params.text,
+                    role: params.role,
+                });
+                if (r.found && r.x != null && r.y != null) {
+                    return { x: r.x, y: r.y, foundBy: r.foundBy ?? "unknown" };
+                }
+            }
+            catch { /* best-effort */ }
+            return null;
+        };
         // 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 };
@@ -2248,8 +2389,35 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
             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") {
-                return { x: x + windowOriginOffset.dx, y: y + windowOriginOffset.dy };
+                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
@@ -2258,7 +2426,8 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
             const inside = x >= 0 && x <= windowOriginOffset.width &&
                 y >= 0 && y <= windowOriginOffset.height;
             if (inside) {
-                return { x: x + windowOriginOffset.dx, y: y + windowOriginOffset.dy };
+                const dpi = applyDpi(x, y);
+                return { x: dpi.x + windowOriginOffset.dx, y: dpi.y + windowOriginOffset.dy };
             }
             return { x, y };
         };
@@ -2286,7 +2455,16 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                     const t = translateXY(params.x, params.y);
                     success = await wm.clickAtPosition(t.x, t.y);
                 }
-                detail = `click at ${params.selector || `(${params.x},${params.y})`}`;
+                else {
+                    // 0.1.50 H1 — UIA selector fallback for click without coords.
+                    const resolved = await resolveDesktopSelector();
+                    if (resolved) {
+                        success = await wm.clickAtPosition(resolved.x, resolved.y);
+                        detail = `click at ${resolved.foundBy}=${params.automation_id || params.text || params.role} → (${resolved.x},${resolved.y})`;
+                        break;
+                    }
+                }
+                detail = `click at ${params.selector || params.automation_id || params.text || params.role || `(${params.x},${params.y})`}`;
                 break;
             case "double_click":
                 if (tt === "browser" && params.selector) {
@@ -2296,7 +2474,15 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                     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})`}`;
+                else {
+                    const resolved = await resolveDesktopSelector();
+                    if (resolved) {
+                        success = await wm.doubleClickAtPosition(resolved.x, resolved.y);
+                        detail = `double_click at ${resolved.foundBy}=${params.automation_id || params.text || params.role} → (${resolved.x},${resolved.y})`;
+                        break;
+                    }
+                }
+                detail = `double_click at ${params.selector || params.automation_id || params.text || params.role || `(${params.x},${params.y})`}`;
                 break;
             case "right_click":
                 if (tt === "browser" && params.selector) {
@@ -2306,7 +2492,15 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                     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})`}`;
+                else {
+                    const resolved = await resolveDesktopSelector();
+                    if (resolved) {
+                        success = await wm.rightClickAtPosition(resolved.x, resolved.y);
+                        detail = `right_click at ${resolved.foundBy}=${params.automation_id || params.text || params.role} → (${resolved.x},${resolved.y})`;
+                        break;
+                    }
+                }
+                detail = `right_click at ${params.selector || params.automation_id || params.text || params.role || `(${params.x},${params.y})`}`;
                 break;
             case "hover":
                 if (tt === "browser" && params.selector) {
@@ -2316,7 +2510,15 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                     const t = translateXY(params.x, params.y);
                     success = await wm.hoverAtPosition(t.x, t.y);
                 }
-                detail = `hover at ${params.selector || `(${params.x},${params.y})`}`;
+                else {
+                    const resolved = await resolveDesktopSelector();
+                    if (resolved) {
+                        success = await wm.hoverAtPosition(resolved.x, resolved.y);
+                        detail = `hover at ${resolved.foundBy}=${params.automation_id || params.text || params.role} → (${resolved.x},${resolved.y})`;
+                        break;
+                    }
+                }
+                detail = `hover at ${params.selector || params.automation_id || params.text || params.role || `(${params.x},${params.y})`}`;
                 break;
             case "type":
                 if (tt === "browser" && params.selector && params.text) {
@@ -2661,7 +2863,7 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
             case "maestro_flow":
                 if (params.maestro_steps) {
                     const mg = await import("./runners/maestro_generator.js");
-                    const cwd = (params.project_dir || params.workspace_root || projectDir);
+                    const cwd = resolveCwd(params);
                     const genResult = await mg.generateMaestroFlow(params.maestro_steps, cwd);
                     if ("error" in genResult) {
                         return { success: false, action, detail: genResult.error };
@@ -2977,7 +3179,7 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
         }
         catch { /* best-effort logging */ }
         return { success, action, detail };
-    }, { tool: "codeloop_interact", cwd: (params.project_dir || params.workspace_root || projectDir), input: params });
+    }, { tool: "codeloop_interact", cwd: resolveCwd(params), input: params });
     return {
         content: withInitHint([{ type: "text", text: JSON.stringify(result, null, 2) }]),
     };
@@ -2999,7 +3201,7 @@ project. After it completes, proceed directly with \`codeloop_verify\`.`, {
     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."),
     project_type: z.enum(["flutter", "web", "mobile", "xcode", "android", "dotnet", "node", "auto"]).default("auto").describe("Project type. Use 'auto' to detect automatically."),
 }, async (params) => {
-    const cwd = (params.project_dir || params.workspace_root || projectDir);
+    const cwd = resolveCwd(params);
     const result = await (async () => {
         const { runInitProject } = await import("./tools/init-project.js");
         const output = await runInitProject({
@@ -3025,7 +3227,7 @@ Returns: counts for attempted / succeeded / requeued events and the queue locati
     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) => {
-    const cwd = (params.project_dir || params.workspace_root || projectDir);
+    const cwd = resolveCwd(params);
     const { flushPersistedUsage } = await import("./auth/usage_tracker.js");
     const result = await flushPersistedUsage(cwd);
     return {
@@ -3113,6 +3315,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 = resolveCwd(params);
+        const { runSelfTest } = await import("./tools/self_test.js");
+        return runSelfTest(cwd);
+    }, { tool: "codeloop_self_test", cwd: resolveCwd(params), 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:
@@ -3138,7 +3376,7 @@ Returns: status, current/latest versions, critical reasons, commands_to_run, aut
         return applyUpdate({ auto_respawn: params.auto_respawn });
     }, {
         tool: "codeloop_apply_update",
-        cwd: params.project_dir || params.workspace_root || projectDir,
+        cwd: resolveCwd(params),
         input: params,
     });
     if (typeof authResult === "object" && authResult !== null && "error" in authResult) {