codeloop-mcp-server 0.1.50 → 0.1.52

package/dist/index.js

@@ -3,6 +3,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, statSync } from "fs";
+import { slugForTargetChangeEntry } from "./tools/c7_slug.js";
 function dirHasFile(dir, predicate) {
     try {
         if (!existsSync(dir))
@@ -379,9 +380,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);
@@ -409,11 +413,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.
@@ -468,6 +515,7 @@ Returns: structured report with pass/fail counts, artifact paths, and next-step
     platform: z.enum(["flutter", "web", "mobile", "xcode", "android", "dotnet", "auto"]).default("auto"),
     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."),
+    tasks_completed: z.array(z.string()).optional().describe("0.1.52 C5 — free-text titles of the tasks the agent claims to have completed in this code change. Cross-checked against the change manifest produced by C1: every claim should map to >= 1 manifest entry and every manifest entry should map to >= 1 claim. Mismatches surface as warnings in the verify response and feed the change_coverage_evidence gate (C3)."),
 }, async (params) => {
     const cwd = resolveCwd(params);
     const explicitDir = params.project_dir || params.workspace_root;
@@ -477,6 +525,7 @@ Returns: structured report with pass/fail counts, artifact paths, and next-step
         const input = {
             scope: params.scope,
             platform: params.platform,
+            tasks_completed: params.tasks_completed,
         };
         const output = await runVerify(input, cfg, cwd);
         await trackUsage(apiKey, "verification_run");
@@ -491,6 +540,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");
@@ -617,6 +671,7 @@ Returns: pass/fail for each gate, overall confidence score, and recommendation.`
     acceptance_path: z.string().default("docs/acceptance/_template.md").describe("Path to the acceptance criteria markdown (absolute or relative to project_dir). Defaults to the template `codeloop_init_project` writes. If neither exists the acceptance gate runs with empty content and uses other signals only."),
     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."),
+    recent_thinking: z.string().optional().describe("0.1.52 C6 — optional dump of the agent's recent thinking / rationale (last few turns of the loop). When present, the gate scans it for anti-rationalisation phrases ('comprehensive verification confirms', 'further interaction would be redundant', 'grid is empty so can't test', etc.) and surfaces specific matches in the continue_fixing postscript so the agent stops repeating the rationalisation and acts on the per-gate next steps instead. Safe to omit — the canonical FORBIDDEN list still ships in the directive without a hit."),
 }, async (params) => {
     const result = await withAuth(async () => {
         const { runGateCheck } = await import("./tools/gate_check.js");
@@ -667,6 +722,14 @@ Returns: pass/fail for each gate, overall confidence score, and recommendation.`
             return `${i + 1}. ${g}${severity}: ${action}`;
         })
             .join("\n");
+        // 0.1.52 C6 — anti-rationalisation directive. Built before the
+        // loopDirective so we can splice the formatted text in.
+        const { scanRecentThinking, buildAntiRationalisationDirective } = await import("./evidence/anti_rationalisation.js");
+        const recentThinking = typeof params.recent_thinking === "string"
+            ? params.recent_thinking
+            : undefined;
+        const rationalisationHits = scanRecentThinking(recentThinking);
+        const antiRationalisationBlock = buildAntiRationalisationDirective(rationalisationHits);
         const loopDirective = [
             "",
             "",
@@ -701,6 +764,9 @@ Returns: pass/fail for each gate, overall confidence score, and recommendation.`
             "MISSING SCREENSHOTS are NEVER a reason to stop — call codeloop_capture_screenshot for each named screen, THEN codeloop_design_compare with mode=\"all\", THEN re-gate.",
             "MISSING VIDEO is NEVER a reason to stop — call codeloop_start_recording, drive the app with codeloop_interact (NOT raw osascript / PowerShell / xdotool), then codeloop_stop_recording, THEN re-gate.",
             "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.",
+            "UNEXERCISED CHANGE-MANIFEST ENTRIES are NEVER a reason to stop — call codeloop_plan_change_journey, follow each step in priority order, pass target_change_entry verbatim on every codeloop_interact / codeloop_capture_screenshot call, THEN re-gate.",
+            "",
+            antiRationalisationBlock,
         ].join("\n");
         return {
             content: withInitHint([{ type: "text", text: resultJson + loopDirective }], resolveCwd(params)),
@@ -778,7 +844,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)
@@ -887,7 +958,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
@@ -1196,7 +1271,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) {
@@ -1233,7 +1311,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
@@ -1251,6 +1331,7 @@ Returns: confirmation + the captured image as an MCP ImageContent block so you c
     run_id: z.string().optional(),
     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."),
+    target_change_entry: z.string().optional().describe("0.1.52 C7 — verbatim display name of the change-manifest entry this screenshot exercises (e.g. 'datagrid_column: \"Product Code\"' or 'PhotometricConfigurations.ProductCode'). When present, the screenshot file is auto-anchored: the filename is prefixed with a slugged form of the entry so the change_coverage_evidence (C3) gate's screenshot scan can credit this evidence to the correct manifest entry without fuzzy matching. The value is also persisted alongside the screenshot path in the response so downstream tools (interaction_replay, gate_check) can use it."),
 }, async (params) => {
     const authResult = await withAuth(async () => {
         const { captureScreenshot } = await import("./runners/screenshot.js");
@@ -1280,7 +1361,19 @@ Returns: confirmation + the captured image as an MCP ImageContent block so you c
         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: desktopApp });
+        // 0.1.52 C7 — auto-anchor the screenshot filename when
+        // target_change_entry is set so the C3 gate's screenshot
+        // scan can credit this evidence to the correct manifest entry
+        // without fuzzy matching. The slug is appended (not prepended)
+        // so existing screen_name semantics still drive the run / replay
+        // tooling that keys off the prefix.
+        const targetChangeEntry = typeof params.target_change_entry === "string"
+            ? params.target_change_entry
+            : undefined;
+        const finalScreenName = targetChangeEntry
+            ? `${params.screen_name}--c7-${slugForTargetChangeEntry(targetChangeEntry)}`
+            : params.screen_name;
+        const result = await captureScreenshot(screenshotsDir, finalScreenName, 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
@@ -1302,7 +1395,7 @@ Returns: confirmation + the captured image as an MCP ImageContent block so you c
             catch { /* best-effort */ }
         }
         await trackUsage(apiKey, "visual_review");
-        return { ...result, windowBounds };
+        return { ...result, windowBounds, target_change_entry: targetChangeEntry ?? null };
     }, { 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) }] };
@@ -1316,6 +1409,11 @@ Returns: confirmation + the captured image as an MCP ImageContent block so you c
             path: result.paths[0],
             method: result.method,
         };
+        if (result.target_change_entry) {
+            payload.target_change_entry = result.target_change_entry;
+            payload.c7_anchor_note =
+                "This screenshot is anchored to a change-manifest entry — the change_coverage_evidence (C3) gate will credit it to that entry without fuzzy matching.";
+        }
         if (result.windowBounds) {
             payload.window_bounds = result.windowBounds;
             payload.coordinate_hint =
@@ -1355,6 +1453,91 @@ Returns: list of discovered screens with routes, navigation triggers, confidence
         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,
@@ -1454,6 +1637,57 @@ ai_substantive_prompts, upload_actions, datagrid_edits }, advice, discovered_int
         content: withInitHint([{ type: "text", text: JSON.stringify(result, null, 2) + driveDirective }]),
     };
 });
+server.tool("codeloop_plan_change_journey", TOOL_BOOTSTRAP + `Build a per-change-entry interaction plan from the most recent change manifest (produced by
+codeloop_verify, 0.1.52 C1+C2). Where codeloop_plan_user_journey enumerates entity-level
+CRUD arcs across the WHOLE app, plan_change_journey is narrower: it only enumerates the
+steps the agent must drive to satisfy the new change_coverage_evidence (C3) gate for the
+features that just shipped in this change.
+
+When to call: AFTER codeloop_verify writes a change_manifest.json AND BEFORE the agent
+starts driving codeloop_interact. The plan is the agent's per-change recording script,
+NOT a substitute for plan_user_journey — call both: plan_user_journey for broad CRUD
+coverage, plan_change_journey for the per-change verification.
+
+Each returned step carries:
+  - target_change_entry: the exact display name from the manifest. Pass this VERBATIM
+    as a codeloop_interact / codeloop_capture_screenshot argument so the C3 gate
+    credits the correct manifest entry without fuzzy matching.
+  - entry_kind: ui_element_added / property_added / method_added /
+    migration_column_added / migration_table_added / layout_restructure.
+  - action: a concrete codeloop_interact (or shell) call template — substitute
+    realistic test data into the placeholders.
+  - empty_state_directive: present when the target is a DataGrid or list — see
+    the C4 seed-first directive.
+
+The preamble explicitly forbids typing into empty grids / clicking buttons that
+empty-state UI hides; seed data first via plan_user_journey's Create arc, a fixture
+script, or a pre-populated artifact.
+
+Returns: { ready, manifest_run_id, total_entries, steps: [...], preamble, message }.`, {
+    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."),
+    workspace_root: z.string().optional().describe("[Alias for project_dir]"),
+    run_id: z.string().optional().describe("Preferred run_id whose change_manifest.json to read. Defaults to the most recent run with a manifest."),
+}, async (params) => {
+    const result = await withAuth(async () => {
+        const { planChangeJourney } = await import("./tools/plan_change_journey.js");
+        return planChangeJourney(resolveCwd(params), params.run_id);
+    }, { tool: "codeloop_plan_change_journey", cwd: resolveCwd(params), input: params });
+    const driveDirective = [
+        "",
+        "",
+        "⚠️ DRIVE THIS PLAN NOW — do not deliberate, do not ask the user ⚠️",
+        "Each step above corresponds to a manifest entry the change_coverage_evidence (C3) gate WILL block on. The next 3 tool calls per step are non-negotiable:",
+        "  1. codeloop_interact — drive the action template; substitute the placeholder with realistic data; ALWAYS pass target_change_entry verbatim from the step.",
+        "  2. codeloop_capture_screenshot — pin the result with target_change_entry from the same step.",
+        "  3. (If the action triggered a modal) codeloop_handle_modal before continuing.",
+        "Empty grids/lists are NOT a valid reason to skip a step — seed data per the preamble first.",
+        "Migration entries (migration_column_added, migration_table_added) MUST be verified via codeloop_interact action='shell' that dumps the live schema; the gate scans build/runtime logs for the column/table name.",
+        "Method entries are implicit — they do NOT need a direct interaction; the gate credits them automatically when the property/column they operate on is exercised.",
+    ].join("\n");
+    return {
+        content: withInitHint([{ type: "text", text: JSON.stringify(result, null, 2) + driveDirective }]),
+    };
+});
 server.tool("codeloop_record_interaction", TOOL_BOOTSTRAP + `Record a fixed-duration video of the app window (blocking). Use for simple captures where no
 interaction is needed during recording. The app is brought to front automatically and the
 IDE is restored after recording completes.
@@ -1863,7 +2097,9 @@ The agent MUST then write the report to docs/DEVELOPMENT_LOG.md and present it t
         return report;
     }, { 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 = [];
@@ -1959,7 +2195,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.
@@ -1982,15 +2223,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");
+        // 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).
@@ -2269,6 +2511,7 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
     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."),
+    target_change_entry: z.string().optional().describe("0.1.52 C3+C4+C7 — verbatim display name of the change-manifest entry this interaction is exercising (e.g. 'datagrid_column: \"Product Code\"' or 'PhotometricConfigurations.ProductCode'). Pass this whenever you're following a step from codeloop_plan_change_journey so the change_coverage_evidence gate can credit the correct manifest entry without fuzzy matching, AND so the empty-state risk detector can compare the target against the manifest before the action is taken."),
 }, async (params) => {
     const result = await withAuth(async () => {
         const action = params.action;
@@ -3120,6 +3363,13 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
             inputArgs.purpose = params.purpose;
         if (params.step)
             inputArgs.step = params.step;
+        // 0.1.52 C3+C7 — preserve the verbatim manifest entry name on the
+        // log so the change_coverage_evidence gate can credit the correct
+        // entry without fuzzy matching.
+        if (params.target_change_entry) {
+            inputArgs.target_change_entry = params
+                .target_change_entry;
+        }
         // Post-action verification readback. Persisted alongside the
         // interaction so a downstream consumer (depth gate, dev report,
         // the agent on the next turn) can confirm the action actually
@@ -3180,8 +3430,113 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
         catch { /* best-effort logging */ }
         return { success, action, detail };
     }, { 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.
+    let 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.";
+    // 0.1.52 C4 — Empty-state seeding directive. Heuristic runs against
+    // the manifest entry the agent claims to be exercising plus the
+    // recent interaction log; when the call looks like a row/cell
+    // action with no prior commit/seed, the postscript appends a HARD
+    // seed-first instruction so the agent doesn't waste a recording
+    // session typing into a non-existent row.
+    try {
+        const { detectEmptyStateRisk, buildEmptyStateDirective } = await import("./runners/empty_state_detector.js");
+        const cwdForC4 = resolveCwd(params);
+        const argsForC4 = params ?? {};
+        const target_change_entry = typeof params.target_change_entry === "string"
+            ? params.target_change_entry
+            : undefined;
+        const verdict = detectEmptyStateRisk({
+            cwd: cwdForC4,
+            target_change_entry,
+            action: typeof params.action === "string"
+                ? params.action
+                : "",
+            args: argsForC4,
+        });
+        const directive = buildEmptyStateDirective(verdict, target_change_entry);
+        if (directive)
+            postscript += directive;
+    }
+    catch {
+        /* best-effort */
+    }
     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 ────────────────────────────────────────