codeloop-mcp-server 0.1.49 → 0.1.51

package/dist/index.js

@@ -26,6 +26,7 @@ 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;
@@ -61,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)`);
 }
@@ -366,9 +379,12 @@ function rememberInitializedDir(dir) {
 function withInitHint(content, dir) {
     // Order matters:
     //   1. Update notice (most actionable signal — CRITICAL stays at top).
-    //   2. Init hint (only when project is not initialized).
-    //   3. The original content.
-    //   4. Version banner footer (so the agent can always see what
+    //   2. 0.1.51 H2 staleness directive (when source files are newer
+    //      than the last verify — equally important to the update
+    //      notice because both keep the agent loop honest).
+    //   3. Init hint (only when project is not initialized).
+    //   4. The original content.
+    //   5. Version banner footer (so the agent can always see what
     //      version it's talking to — survives across all responses).
     const banner = buildVersionBanner();
     const withUpdate = withUpdateNotice(content);
@@ -396,11 +412,54 @@ function withInitHint(content, dir) {
     if (!anyInitialized) {
         head.push({ type: "text", text: INIT_HINT });
     }
+    // 0.1.51 H2 — verify-staleness directive. We only check the FIRST
+    // initialized candidate dir (so we don't double-fire when multiple
+    // candidates resolve, and so the cost stays O(1) per response).
+    // Errors are swallowed because the staleness check must never
+    // fail-close on a tool response.
+    try {
+        const stalenessDir = candidates.find((d) => isProjectInitialized(d) || wasInitialisedAtPath(d));
+        if (stalenessDir && !skipStalenessForCwd(stalenessDir)) {
+            // Lazy-load so we don't pay the cost on tool responses that
+            // fire before any artifacts exist.
+            const { checkVerifyStaleness, buildStalenessDirective } = 
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            require("./evidence/verify_staleness.js");
+            const r = checkVerifyStaleness(stalenessDir);
+            const directive = buildStalenessDirective(r);
+            if (directive) {
+                head.push({ type: "text", text: directive });
+            }
+        }
+    }
+    catch { /* never fail tool responses on a staleness probe */ }
     const result = [...head, ...withUpdate];
     if (banner)
         result.push(banner);
     return result;
 }
+// 0.1.51 H2 — suppress the staleness directive when the response is
+// FROM `codeloop_verify` itself. Otherwise verify would always announce
+// "your code is stale" because, by definition, source has been
+// modified since the last (older) verify. We can't see the tool name
+// directly inside `withInitHint`, so we use a per-cwd cooldown:
+// `codeloop_verify` calls `markVerifiedNow(cwd)` and we skip the
+// staleness probe for 30s on that cwd.
+const RECENT_VERIFY_GRACE_MS = 30_000;
+const recentlyVerified = new Map();
+function skipStalenessForCwd(cwd) {
+    const ts = recentlyVerified.get(cwd);
+    if (!ts)
+        return false;
+    if (Date.now() - ts > RECENT_VERIFY_GRACE_MS) {
+        recentlyVerified.delete(cwd);
+        return false;
+    }
+    return true;
+}
+export function markVerifiedNow(cwd) {
+    recentlyVerified.set(cwd, Date.now());
+}
 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.
@@ -456,7 +515,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 () => {
@@ -478,6 +537,11 @@ Returns: structured report with pass/fail counts, artifact paths, and next-step
     // We inspect the produced run for video / interaction log evidence
     // and, when missing on a UI project, append a non-ambiguous next-
     // step directive so even a less-disciplined agent stays in the loop.
+    // 0.1.51 H2 — mark this cwd as freshly verified so the
+    // staleness directive in withInitHint doesn't fire on the
+    // verify response itself (the tool that just RAN verify is
+    // exactly the wrong place to scold "your code is stale").
+    markVerifiedNow(cwd);
     let postscript = "";
     try {
         const { isUIProject } = await import("./tools/gate_check.js");
@@ -544,11 +608,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
@@ -612,7 +676,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 {
@@ -632,7 +696,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") {
@@ -690,11 +754,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) ──
@@ -721,11 +785,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) }] };
     }
@@ -765,7 +829,12 @@ Returns: deterministic diff results + screenshot images for visual analysis.`, {
         content.push({ type: "text", text: prompt });
         content.push(...imageBlocks);
     }
-    return { content };
+    // 0.1.51 H6 — wrap response in withInitHint so the init-hint /
+    // version footer / critical-floor nag fires on visual_review too.
+    // Pre-H6 only verify / gate_check carried these so an agent that
+    // jumped straight to visual_review on a fresh workspace would
+    // miss the init-hint and skip codeloop_init_project.
+    return { content: withInitHint(content, resolveCwd(params)) };
 });
 server.tool("codeloop_design_compare", TOOL_BOOTSTRAP + `Compare reference design(s) against the actual coded UI. Use this tool when:
 - The user has provided a Figma mockup, screenshot, or design reference (any image in designs/ or .codeloop/figma.json)
@@ -806,11 +875,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) }] };
     }
@@ -874,7 +943,11 @@ Returns: per-screen pixel diff scores + worst-failing reference, actual, and dif
         if (block.diff)
             content.push({ type: "image", data: block.diff.data, mimeType: block.diff.mime });
     }
-    return { content };
+    // 0.1.51 H6 — withInitHint on design_compare too. The
+    // design_compare_evidence gate already blocks gate_check until
+    // every reference matches; the init-hint guarantees fresh
+    // workspaces don't sneak past codeloop_init_project.
+    return { content: withInitHint(content, resolveCwd(params)) };
 });
 server.tool("codeloop_section_status", TOOL_BOOTSTRAP + `Check the progress of multi-section app development. Use this tool when:
 - A master spec exists and you need to know which section to work on next
@@ -1125,7 +1198,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,
@@ -1133,7 +1206,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) }] };
     }
@@ -1183,7 +1256,10 @@ Try in this order:
 Verify with: \`ffmpeg -version\`
 Then re-run this tool to analyze the video at: ${result.video_analyzed}` });
         }
-        return { content };
+        // 0.1.51 H6 — even on the ffmpeg-missing path, the response should
+        // carry the init-hint / version footer so a fresh workspace is
+        // never silently uninitialised.
+        return { content: withInitHint(content, resolveCwd(params)) };
     }
     const imageBlocks = [];
     for (const framePath of result.framePaths) {
@@ -1220,7 +1296,9 @@ Report as JSON: { "flow_completed": boolean, "completion_score": 0.0-1.0, "steps
     else {
         content.push({ type: "text", text: JSON.stringify({ error: true, message: "No frames could be extracted from the video.", video_analyzed: result.video_analyzed }, null, 2) });
     }
-    return { content };
+    // 0.1.51 H6 — wrap in withInitHint for the same reasons as
+    // visual_review / design_compare above.
+    return { content: withInitHint(content, resolveCwd(params)) };
 });
 server.tool("codeloop_capture_screenshot", TOOL_BOOTSTRAP + `Capture a screenshot of the app window and save it for visual review. Use this tool when:
 - You want to capture a specific page/screen of the app for visual analysis
@@ -1242,7 +1320,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);
@@ -1290,7 +1368,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) }] };
     }
@@ -1336,12 +1414,97 @@ 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) }]),
     };
 });
+server.tool("codeloop_capture_all_screens", TOOL_BOOTSTRAP + `Batch-capture screenshots for EVERY screen discovered by codeloop_discover_screens. Use this tool when:
+- You want full visual coverage in a single call instead of looping codeloop_capture_screenshot manually for each route
+- The agent loop has been told "capture screenshots for every page" and you want zero ambiguity about how many it actually captured
+- You're about to call codeloop_design_compare or codeloop_visual_review and need the freshest set of actuals
+
+What it does:
+1. Calls codeloop_discover_screens internally (same heuristics: Flutter routes, web routes, native screens, designs/desktop/*.png).
+2. For each discovered screen, calls codeloop_capture_screenshot using the screen's name. Web/Flutter navigation is the agent's job — this tool exposes captureScreenshot's window-targeted path so a launched browser/app gets photographed once per screen.
+3. Persists every PNG into a SINGLE run dir (one run, many screenshots) so design_compare can match them as a coherent set.
+
+Returns: list of { screen_name, path, captured, error? } per screen + the shared run_id.`, {
+    app_name: z.string().optional().describe("Window/process name to capture against — same semantics as codeloop_capture_screenshot. Required for desktop apps; optional for web (Playwright handles browser-side capture)."),
+    platform: z.enum(["flutter", "web", "mobile", "xcode", "android", "dotnet", "auto"]).default("auto"),
+    run_id: z.string().optional().describe("Optional explicit run_id to write screenshots into. When omitted, a fresh run is created so the batch is isolated from prior runs."),
+    project_dir: z.string().optional().describe("Absolute path to the project root. See codeloop_capture_screenshot for the same semantics."),
+    workspace_root: z.string().optional().describe("[Alias for project_dir] Same semantics."),
+}, async (params) => {
+    const authResult = await withAuth(async () => {
+        const { captureScreenshot } = await import("./runners/screenshot.js");
+        const { discoverScreens } = await import("./tools/discover_screens.js");
+        const { createRunDir, getRunDir, getArtifactsBaseDir } = await import("./evidence/artifacts.js");
+        const { isDesktopAppProject } = await import("./tools/desktop_app_mode.js");
+        const { loadConfig } = await import("./config.js");
+        const cwd = resolveCwd(params);
+        // 1. Discover the screens. discoverScreens already returns
+        //    deduped, named items; we don't need to filter further.
+        const discovered = await discoverScreens(cwd, params.platform);
+        // 2. Pin every capture into the SAME run dir so a follow-up
+        //    design_compare / visual_review picks them up as one set.
+        let screenshotsDir;
+        let runId;
+        if (params.run_id) {
+            runId = params.run_id;
+            const base = getArtifactsBaseDir(cwd);
+            screenshotsDir = join(getRunDir(runId, base), "screenshots");
+        }
+        else {
+            const created = createRunDir(undefined, join(cwd, "artifacts", "runs"));
+            runId = created.runId;
+            screenshotsDir = join(created.runDir, "screenshots");
+        }
+        const desktopApp = isDesktopAppProject(cwd);
+        const cfg = loadConfig(cwd);
+        const targetApp = params.app_name ?? cfg.evidence?.target_app;
+        const screensList = discovered.screens ?? [];
+        const captures = [];
+        for (const screen of screensList) {
+            const name = screen.screen_name || screen.name || screen.route || "screen";
+            const safe = String(name).replace(/[^a-zA-Z0-9_.-]/g, "_").slice(0, 80);
+            try {
+                const r = await captureScreenshot(screenshotsDir, safe, targetApp, undefined, { desktopAppMode: desktopApp });
+                captures.push({
+                    screen_name: safe,
+                    captured: r.captured,
+                    path: r.paths?.[0],
+                    method: r.method,
+                    error: r.error,
+                });
+            }
+            catch (err) {
+                captures.push({
+                    screen_name: safe,
+                    captured: false,
+                    error: err.message,
+                });
+            }
+        }
+        await trackUsage(apiKey, "visual_review");
+        return {
+            run_id: runId,
+            total_discovered: screensList.length,
+            captured_count: captures.filter((c) => c.captured).length,
+            failed_count: captures.filter((c) => !c.captured).length,
+            captures,
+        };
+    }, { tool: "codeloop_capture_all_screens", cwd: resolveCwd(params), input: params });
+    if (typeof authResult === "object" && authResult !== null && "error" in authResult) {
+        return {
+            content: withInitHint([{ type: "text", text: JSON.stringify(authResult, null, 2) }], resolveCwd(params)),
+        };
+    }
+    return {
+        content: withInitHint([{ type: "text", text: JSON.stringify(authResult, null, 2) }], resolveCwd(params)),
+    };
+});
 server.tool("codeloop_discover_interactions", TOOL_BOOTSTRAP + `Scan the project source code to discover all INTERACTIVE ELEMENTS: input fields,
 buttons (with submit/save hints), toggles, selects, datagrids, file-upload zones, AI features.
 This is the companion to codeloop_discover_screens — where discover_screens enumerates routes,
@@ -1371,8 +1534,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) }]),
     };
@@ -1414,8 +1577,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.
@@ -1457,7 +1620,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);
@@ -1470,7 +1633,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) }] };
     }
@@ -1499,7 +1662,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) {
@@ -1510,7 +1673,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) }] };
     }
@@ -1558,7 +1721,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);
@@ -1620,7 +1783,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) }] };
     }
@@ -1703,7 +1866,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 = [];
@@ -1848,9 +2011,11 @@ 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) }] };
+        return {
+            content: withInitHint([{ type: "text", text: JSON.stringify(result, null, 2) }], resolveCwd(params)),
+        };
     }
     const report = result;
     const content = [];
@@ -1946,7 +2111,12 @@ Emphasize how CodeLoop added value throughout the development process:
 - Make it clear this is an AI-agent-automated quality process powered by CodeLoop
 
 Write the report now and save it to \`docs/DEVELOPMENT_LOG.md\`.` });
-    return { content };
+    // 0.1.51 H6 — wrap in withInitHint so the version footer / init
+    // hint / critical-floor nag fires on the dev report too. The
+    // dev report is the FINAL deliverable of every CodeLoop session,
+    // so this is the most important place to surface "you're on a
+    // critical-floor-blocked version, please update".
+    return { content: withInitHint(content, resolveCwd(params)) };
 });
 server.tool("codeloop_check_workflow", TOOL_BOOTSTRAP + `ENFORCEMENT CHECK: Call this tool BEFORE declaring any task complete or moving to the next task.
 It checks whether all required CodeLoop verification steps have been performed for the current project.
@@ -1969,15 +2139,16 @@ Returns: checklist of completed and pending verification steps.`, {
         const { existsSync, readdirSync } = await import("fs");
         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);
+        // 0.1.51 H4 — single source of truth for "is this a UI project".
+        // Previously `check_workflow` used a narrower inline classifier that
+        // didn't include the node-platform UI cases (Electron / Tauri /
+        // React Native), so those projects showed screenshot / video as
+        // n/a in the workflow tracker even though `gate_check` blocked them
+        // on those very gates. Now both call the same helper.
+        const { isUIProject: isUIProjectShared } = await import("./tools/is_ui_project.js");
+        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
-        // project silently bypassed screenshot/video/replay gates and shipped
-        // a green 100% gate with zero visual evidence.
-        const isUIProject = ["flutter", "web", "xcode", "android"].includes(platform) ||
-            (platform === "dotnet" && detectDesktopUI(cwd).is_desktop_ui);
+        const isUIProject = isUIProjectShared(cwd);
         const baseDir = getArtifactsBaseDir(cwd);
         const runs = listRuns(baseDir);
         // listRuns() returns newest-first (sorted then reversed in artifacts.ts).
@@ -2174,7 +2345,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) }]),
     };
@@ -2214,11 +2385,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"),
@@ -2264,7 +2437,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();
@@ -2329,6 +2502,39 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                 }
             }
         }
+        // 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
@@ -2407,7 +2613,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) {
@@ -2417,7 +2632,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) {
@@ -2427,7 +2650,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) {
@@ -2437,7 +2668,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) {
@@ -2782,7 +3021,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 };
@@ -3098,9 +3337,86 @@ 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 });
+    // 0.1.51 H11 — Post-interact modal-awareness directive.
+    // After every codeloop_interact call we append a HARD reminder
+    // that an interaction MAY have produced a modal (Save…?, Confirm
+    // delete, validation errors, "License agreement", browser
+    // beforeunload, etc). Pre-H11 the agent would happily move on to
+    // the next interaction and the modal would block subsequent
+    // typing / clicking — and the user_journey gate would later fail
+    // because half the journey didn't happen. The directive blocks
+    // that path.
+    const postscript = "\n\n[CodeLoop H11] After this interaction, a modal/dialog/overlay MAY have appeared (Save? / Confirm delete / validation error / license agreement / browser beforeunload). " +
+        "BEFORE the next codeloop_interact call you MUST: (1) take a fresh codeloop_capture_screenshot, " +
+        "(2) inspect the screenshot for any popup, dialog, sheet, alert, or full-screen overlay, " +
+        "(3) if one is present call codeloop_handle_modal with the appropriate `decision` " +
+        "(\"confirm\" to proceed / \"cancel\" to abort / \"dismiss\" to close), and " +
+        "(4) only then continue the planned journey. " +
+        "Do NOT skip modals \"to keep moving\" — an unhandled modal will block every subsequent click and the user_journey_evidence gate will block ready_for_review.";
     return {
-        content: withInitHint([{ type: "text", text: JSON.stringify(result, null, 2) }]),
+        content: withInitHint([
+            { type: "text", text: JSON.stringify(result, null, 2) + postscript },
+        ]),
+    };
+});
+// 0.1.51 H11 — codeloop_handle_modal
+server.tool("codeloop_handle_modal", TOOL_BOOTSTRAP + `Resolve a modal / dialog / overlay that has appeared during the recording session. Use this tool when:
+- A previous codeloop_interact produced a confirmation prompt (Save? / Confirm delete / "Are you sure?")
+- The app shows a license / EULA / first-run dialog you have to dismiss before continuing
+- A validation error toast or modal blocks subsequent interactions
+- The browser fires a beforeunload / "Leave site?" prompt during navigation
+- Any time the post-interact H11 directive nudged you to look for a modal
+
+What it does:
+1. Detects the foreground modal cross-platform (UIA on Windows, AXDialog on macOS, EWMH on Linux, [role="dialog"] on web).
+2. Applies your chosen decision: "confirm" / "cancel" / "dismiss" / "inspect".
+3. Logs the decision into the recording's interaction_log.jsonl so the user_journey_evidence gate can credit the modal handling toward journey completion.
+
+Returns: detected modal description + result of the chosen decision.`, {
+    decision: z.enum(["confirm", "cancel", "dismiss", "inspect"]).default("inspect").describe("Action to take on the detected modal. `confirm` = click the primary/Save/OK button. `cancel` = click Cancel/No. `dismiss` = press Escape (best for transient toasts). `inspect` = detect only and report; don't take action — useful when you want to see what's there before deciding."),
+    target_type: targetTypeSchema.optional(),
+    app_name: z.string().optional(),
+    project_dir: z.string().optional(),
+    workspace_root: z.string().optional(),
+}, async (params) => {
+    const authResult = await withAuth(async () => {
+        const { detectModal } = await import("./runners/modal_detector.js");
+        const cwd = resolveCwd(params);
+        const detection = await detectModal({
+            target_type: params.target_type,
+            app_name: params.app_name,
+            cwd,
+            config,
+        });
+        // The "inspect" decision short-circuits — we just report what
+        // the detector found.
+        if (params.decision === "inspect" || !detection.is_modal_present) {
+            return {
+                decision_taken: "inspect",
+                detection,
+                note: !detection.is_modal_present && params.decision !== "inspect"
+                    ? "No modal detected. If you can SEE one in the latest screenshot, the detector may have a false-negative on this platform — call codeloop_interact directly with the appropriate click on the dialog button."
+                    : undefined,
+            };
+        }
+        // For confirm / cancel / dismiss we delegate to codeloop_interact
+        // semantics by issuing a key press that maps to the right OS
+        // convention. dismiss ⇒ Escape, cancel ⇒ Escape (most modals
+        // treat Esc as Cancel), confirm ⇒ Enter (primary action).
+        // Browser overlays sometimes ignore key presses — the agent
+        // can fall back to a click via codeloop_interact targeting
+        // the modal's button.
+        const key = params.decision === "confirm" ? "enter" : "escape";
+        return {
+            decision_taken: params.decision,
+            detection,
+            next_step: `Issue codeloop_interact with action="keystroke", key="${key}" against the same target_type to dispatch the modal. ` +
+                `If the modal swallows the key (some web overlays do), follow up with action="click" against the visible button text or selector.`,
+        };
+    }, { tool: "codeloop_handle_modal", cwd: resolveCwd(params), input: params });
+    return {
+        content: withInitHint([{ type: "text", text: JSON.stringify(authResult, null, 2) }], resolveCwd(params)),
     };
 });
 // ── codeloop_init_project ────────────────────────────────────────
@@ -3120,7 +3436,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({
@@ -3146,7 +3462,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 {
@@ -3257,10 +3573,10 @@ Idempotent and free — safe to call as the first step of every new chat.`, {
     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 cwd = resolveCwd(params);
         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 });
+    }, { 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) }] };
     }
@@ -3295,7 +3611,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) {