@loadmill/droid-cua 2.39.0 → 2.40.0

package/README.md

@@ -158,8 +158,13 @@ droid-cua skill install codex
 droid-cua skill install codex --local
 ```
 
-Use `droid-cua skill status <agent>` to inspect an installation and
-`droid-cua skill uninstall <agent>` to remove it. Installed skill
+Use `droid-cua skill status <agent>` to see the installed and bundled skill
+versions and installation path; add `--local` to inspect a project installation.
+The skill version is stored in `SKILL.md` under `metadata.version`, independently
+of the CLI package version. Older copies without version metadata show `unknown`.
+The `modified` status means the files differ from the bundled copy, which can
+indicate an older release or local edits even when version labels match.
+Use `droid-cua skill uninstall <agent>` to remove an installation. Installed skill
 files are never overwritten or removed after local modification unless `--force`
 is supplied. After upgrading the npm package, update an installed skill explicitly:
 
@@ -239,7 +244,7 @@ backward compatibility.
 Example headless config:
 ```json
 {
-  "cuaModel": "gpt-5.4",
+  "cuaModel": "gpt-6-sol",
   "promptCustomizations": {
     "basePromptInstructions": "",
     "designModeInstructions": "",
@@ -295,10 +300,13 @@ Supported CLI options include:
 - `--debug`
 
 `--cua-model` accepts `loadmill-smart`, `loadmill-pulse`, `loadmill-beacon`,
-`gpt-5.6-terra`, `gpt-5.6-luna`, and `gpt-5.4`. OpenAI models use direct OpenAI
-mode and require `OPENAI_API_KEY`.
+`gpt-6-sol`, and `gpt-6-luna`. OpenAI models use direct OpenAI mode and require
+`OPENAI_API_KEY`. Saved direct OpenAI selections of GPT-5.6 Terra, GPT-5.6 Luna,
+or GPT-5.4 move to GPT-6 Sol, GPT-6 Luna, or GPT-6 Sol, respectively.
 
-Desktop control supports macOS and Windows. In the desktop app, enable **Experimental desktop control** at the bottom of Settings to show Desktop in the platform picker. Desktop runs use visual input by default: they capture the selected window and send physical pointer and keyboard input at the model's coordinates. Use `--desktop-input accessibility` for cursor-free CLI input instead. macOS requires Screen & System Audio Recording and Accessibility permissions for Droid or the terminal running the CLI. Windows targets must run at the same integrity level as Droid; a non-elevated Droid process cannot inject input into an elevated application.
+Desktop control supports macOS and Windows. In the desktop app, enable **Experimental desktop control** at the bottom of Settings to show Desktop in the platform picker. Desktop runs use visual input by default: Droid shows a system notice for three seconds before taking control, brings the selected window to the foreground, then sends physical pointer and keyboard input at the model's coordinates. The three-second delay is fixed; once the test starts, use Stop in Droid to end it. Avoid using the mouse or keyboard during the run. When the run ends, Droid leaves the target window in front and shows another system notice that control has finished, including when the run fails or is stopped. CLI runs also leave the target in front. Use `--desktop-input accessibility` for cursor-free CLI input instead. macOS requires Screen & System Audio Recording and Accessibility permissions for Droid or the terminal running the CLI. Windows targets must run at the same integrity level as Droid; a non-elevated Droid process cannot inject input into an elevated application. If Windows returns an all-black window capture, Droid brings the target back to the foreground and crops the visible desktop to the window's visible frame, excluding its invisible resize border. The crop is resized only after extraction to preserve window detail. The fallback logs a warning and requires the target to remain unobstructed on the primary display; off-screen portions appear black. With accessibility input, bring the target to the foreground yourself when requested.
+
+The system notices are shown only for desktop control runs started in the desktop app. On macOS, they may not appear in the unsigned Electron dev app; verify them in a signed packaged build.
 
 Config and precedence rules:
 - Use `--config <file>` to supply prompt-affecting settings for headless runs.

package/build/index.js

@@ -537,6 +537,7 @@ async function main() {
             app: targetConfig.desktopApp,
             windowId: targetConfig.desktopWindow,
             inputMode: targetConfig.desktopInput,
+            focusOnConnect: true,
             excludePids: [process.pid],
         });
         targetId = desktopController.deviceId;

package/build/src/cli/headless-execution-config.js

@@ -2,7 +2,7 @@ import path from "path";
 import { readFile } from "fs/promises";
 import { DEFAULT_CONTEXT_OPTIMIZATION_THRESHOLD, MAX_CONTEXT_OPTIMIZATION_THRESHOLD, MIN_CONTEXT_OPTIMIZATION_THRESHOLD, } from "../core/context-optimization.js";
 import { AIM_ASSIST_MODES, DEFAULT_AIM_ASSIST_MODE } from "../core/aim-assist.js";
-import { CUA_MODELS, DEFAULT_OPENAI_CUA_MODEL, isOpenAiCuaModel, isValidCuaModel, resolveCuaModel } from "../core/cua-models.js";
+import { CUA_MODELS, DEFAULT_OPENAI_CUA_MODEL, isOpenAiCuaModel, isValidCuaModel, resolveCuaModel, upgradeLegacyCuaModel } from "../core/cua-models.js";
 import { LLM_PROVIDER_MODES, isValidLlmProviderMode, resolveLlmProviderMode } from "../core/runtime-config.js";
 import { parseSecretsOverrideString } from "../core/secrets.js";
 function createEmptyPromptCustomizations() {
@@ -21,10 +21,11 @@ function assertNonEmptyString(value, label) {
     }
 }
 function validateCuaModel(value, label) {
-    if (typeof value !== "string" || !isValidCuaModel(value)) {
+    const upgraded = typeof value === "string" ? upgradeLegacyCuaModel(value) : value;
+    if (!isValidCuaModel(upgraded)) {
         throw new Error(`${label} must be one of: ${CUA_MODELS.join(", ")}.`);
     }
-    return value;
+    return upgraded;
 }
 function validateAimAssistMode(value, label) {
     if (typeof value !== "string" || !AIM_ASSIST_MODES.includes(value)) {
@@ -44,8 +45,8 @@ function readEnvDefaultCuaModel() {
     // OpenAI model, stay on the OpenAI default rather than crossing over to the
     // global (Loadmill) default.
     if (typeof envValue === "string" && envValue.trim()) {
-        const trimmed = envValue.trim();
-        return isOpenAiCuaModel(trimmed) ? trimmed : DEFAULT_OPENAI_CUA_MODEL;
+        const upgraded = upgradeLegacyCuaModel(envValue.trim());
+        return isOpenAiCuaModel(upgraded) ? upgraded : DEFAULT_OPENAI_CUA_MODEL;
     }
     return resolveCuaModel(envValue);
 }

package/build/src/cli/skill-command.js

@@ -12,7 +12,7 @@ const SUBCOMMANDS = new Set(["install", "status", "uninstall"]);
 const ALLOWED_OPTIONS = new Set(["_", "local", "force", "h", "help"]);
 const COMMAND_DESCRIPTIONS = Object.freeze({
     install: "Install Droid CUA skill for a coding agent",
-    status: "Show Droid CUA skill status for a coding agent",
+    status: "Show installation status and installed/bundled skill versions",
     uninstall: "Uninstall Droid CUA skill for a coding agent",
 });
 function skillCommandHelp(subcommand) {
@@ -53,7 +53,7 @@ function skillRootHelp() {
         "",
         "Commands:",
         "  install    Install the skill",
-        "  status     Show installation status",
+        "  status     Show installation status and skill versions",
         "  uninstall  Uninstall the skill",
     ].join("\n");
 }
@@ -103,6 +103,18 @@ async function directoryMatches(sourcePath, destinationPath) {
     ]);
     return JSON.stringify(sourceSnapshot) === JSON.stringify(destinationSnapshot);
 }
+// Read the bundled skill's block-style metadata.version scalar without a YAML dependency.
+async function readSkillVersion(skillPath) {
+    if (await pathType(skillPath) !== "directory")
+        return null;
+    if (await pathType(path.join(skillPath, "SKILL.md")) !== "file")
+        return null;
+    const markdown = await readFile(path.join(skillPath, "SKILL.md"), "utf8");
+    const frontmatter = markdown.replace(/\r\n/g, "\n").match(/^---\n([\s\S]*?)\n---(?:\n|$)/)?.[1];
+    const metadata = frontmatter?.match(/^metadata:[ \t]*\n((?:[ \t]+[^\n]*(?:\n|$))*)/m)?.[1];
+    const value = metadata?.match(/^  version:[ \t]*(?:"([^"\n]+)"|'([^'\n]+)'|([^\s#]+))[ \t]*(?:#.*)?$/m);
+    return value ? (value[1] ?? value[2] ?? value[3]) : null;
+}
 async function getInstallationState(sourcePath, destinationPath) {
     if (await pathType(destinationPath) === "missing")
         return "not-installed";
@@ -214,7 +226,12 @@ export async function runSkillCommand({ args, cwd = process.cwd(), home = os.hom
     }
     for (const destination of states) {
         if (command.subcommand === "status") {
-            output.log(`${destination.displayName}: ${stateLabel(destination.state)} at ${destination.path}`);
+            const [installedVersion, bundledVersion] = await Promise.all([
+                readSkillVersion(destination.path),
+                readSkillVersion(bundledSkillPath),
+            ]);
+            const installedLabel = destination.state === "not-installed" ? "not installed" : installedVersion ?? "unknown";
+            output.log(`${destination.displayName}: ${stateLabel(destination.state)} at ${destination.path}\nInstalled skill version: ${installedLabel}\nBundled skill version: ${bundledVersion ?? "unknown"}`);
         }
         else if (command.subcommand === "install") {
             if (destination.state === "installed") {

package/build/src/core/cua-models.js

@@ -1,4 +1,4 @@
-export const DEFAULT_OPENAI_CUA_MODEL = "gpt-5.4";
+export const DEFAULT_OPENAI_CUA_MODEL = "gpt-6-sol";
 export const DEFAULT_LOADMILL_CUA_MODEL = "loadmill-smart";
 export const DEFAULT_CUA_MODEL = DEFAULT_LOADMILL_CUA_MODEL;
 export const CUA_CONVERSATION_POLICIES = Object.freeze({
@@ -28,27 +28,28 @@ export const CUA_MODEL_OPTIONS = Object.freeze([
         label: "Loadmill - Beacon",
     }),
     Object.freeze({
-        id: "gpt-5.6-terra",
+        id: "gpt-6-sol",
         providerMode: "openai",
         providerLabel: "OpenAI",
-        name: "GPT-5.6 Terra",
-        label: "OpenAI GPT-5.6 Terra",
+        name: "GPT-6 Sol",
+        label: "OpenAI GPT-6 Sol",
     }),
     Object.freeze({
-        id: "gpt-5.6-luna",
+        id: "gpt-6-luna",
         providerMode: "openai",
         providerLabel: "OpenAI",
-        name: "GPT-5.6 Luna",
-        label: "OpenAI GPT-5.6 Luna",
-    }),
-    Object.freeze({
-        id: "gpt-5.4",
-        providerMode: "openai",
-        providerLabel: "OpenAI",
-        name: "GPT-5.4",
-        label: "OpenAI GPT-5.4",
+        name: "GPT-6 Luna",
+        label: "OpenAI GPT-6 Luna",
     }),
 ]);
+const LEGACY_OPENAI_CUA_MODELS = Object.freeze({
+    "gpt-5.6-terra": "gpt-6-sol",
+    "gpt-5.6-luna": "gpt-6-luna",
+    "gpt-5.4": "gpt-6-sol",
+});
+export function upgradeLegacyCuaModel(value) {
+    return LEGACY_OPENAI_CUA_MODELS[value] ?? value;
+}
 export const CUA_MODELS = Object.freeze(CUA_MODEL_OPTIONS.map((option) => option.id));
 export const OPENAI_CUA_MODELS = Object.freeze(CUA_MODEL_OPTIONS
     .filter((option) => option.providerMode === "openai")
@@ -70,7 +71,8 @@ export function isLoadmillCuaModel(value) {
     return LOADMILL_CUA_MODEL_SET.has(value);
 }
 export function resolveCuaModel(value) {
-    return isValidCuaModel(value) ? value : DEFAULT_CUA_MODEL;
+    const upgraded = upgradeLegacyCuaModel(value);
+    return isValidCuaModel(upgraded) ? upgraded : DEFAULT_CUA_MODEL;
 }
 export function resolveCuaModelProviderMode(value) {
     const normalized = resolveCuaModel(value);

package/build/src/core/droid-cua-run-usage.js

@@ -3,29 +3,26 @@ const OPENAI_GPT_5_4_PRICING = Object.freeze({
     inputPerMillionUsd: 2.5,
 });
 const OPENAI_GPT_5_6_TERRA_PRICING = Object.freeze({
-    inputPerMillionUsd: 2.5,
+    inputPerMillionUsd: 2,
 });
 const OPENAI_GPT_5_6_LUNA_PRICING = Object.freeze({
-    inputPerMillionUsd: 1,
+    inputPerMillionUsd: 0.2,
+});
+const OPENAI_GPT_6_SOL_PRICING = Object.freeze({
+    inputPerMillionUsd: 2,
+});
+const OPENAI_GPT_6_LUNA_PRICING = Object.freeze({
+    inputPerMillionUsd: 0.1,
 });
 const MODEL_PRICING = Object.freeze({
-    "gpt-5.6-terra": Object.freeze({
-        ...OPENAI_GPT_5_6_TERRA_PRICING,
-    }),
-    "gpt-5.6-luna": Object.freeze({
-        ...OPENAI_GPT_5_6_LUNA_PRICING,
-    }),
-    "gpt-5.4": Object.freeze({
-        ...OPENAI_GPT_5_4_PRICING,
-    }),
-    // Loadmill Smart currently routes to GPT-5.6 Terra behind the Loadmill LLM gateway.
-    // Keep this explicit so pricing can be updated here if the backing model changes.
-    "loadmill-smart": Object.freeze({
-        ...OPENAI_GPT_5_6_TERRA_PRICING,
-    }),
-    "loadmill-pulse": Object.freeze({
-        ...OPENAI_GPT_5_6_LUNA_PRICING,
-    }),
+    "gpt-6-sol": OPENAI_GPT_6_SOL_PRICING,
+    "gpt-6-luna": OPENAI_GPT_6_LUNA_PRICING,
+    "gpt-5.6-terra": OPENAI_GPT_5_6_TERRA_PRICING,
+    "gpt-5.6-luna": OPENAI_GPT_5_6_LUNA_PRICING,
+    "gpt-5.4": OPENAI_GPT_5_4_PRICING,
+    // Loadmill Smart and Pulse route to GPT-6 Sol and Luna, respectively.
+    "loadmill-smart": OPENAI_GPT_6_SOL_PRICING,
+    "loadmill-pulse": OPENAI_GPT_6_LUNA_PRICING,
 });
 function finiteNumber(value) {
     return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
@@ -41,6 +38,12 @@ export function normalizeDroidCuaCostModel(model) {
     if (typeof model !== "string") {
         return null;
     }
+    if (model === "gpt-6-sol" || model.startsWith("gpt-6-sol-")) {
+        return "gpt-6-sol";
+    }
+    if (model === "gpt-6-luna" || model.startsWith("gpt-6-luna-")) {
+        return "gpt-6-luna";
+    }
     if (model === "gpt-5.6-terra" || model.startsWith("gpt-5.6-terra-")) {
         return "gpt-5.6-terra";
     }

package/build/src/desktop/computer-use.js

@@ -1,6 +1,8 @@
 import { buildActionEventMeta } from "../device/action-event-meta.js";
 import { buildTypeActionPayload, buildTypeActionText, } from "../device/sensitive-action.js";
 import { getConfiguredStepDelayMs } from "../utils/step-delay.js";
+import { getWindowsVisibleBounds } from "./windows-visible-bounds.js";
+import sharp from "sharp";
 const SCREENSHOT_WIDTH = 1440;
 const ACCESSIBILITY_HIT_TOLERANCE = 12;
 const MACOS_CAPTURE_INSETS = { left: 50, right: 50, top: 38, bottom: 62 };
@@ -26,6 +28,57 @@ function assertResult(result, label) {
         throw new Error(result.content?.find((item) => item.type === "text")?.text || `${label} failed.`);
     }
 }
+function readScreenshot(result) {
+    const image = result.content?.find((item) => item.type === "image");
+    const sizeText = result.content?.find((item) => item.type === "text")?.text || "";
+    const size = /^(\d+)x(\d+)$/.exec(sizeText.trim());
+    if (!image?.data || !size)
+        throw new Error("Desktop screenshot returned no image or dimensions.");
+    return { data: image.data, width: Number(size[1]), height: Number(size[2]) };
+}
+async function isBlackScreenshot(data) {
+    const { channels } = await sharp(Buffer.from(data, "base64")).stats();
+    return channels.slice(0, 3).every((channel) => channel.max === 0);
+}
+async function captureWindowFromDesktop(native, bounds) {
+    const display = native.getDisplaySize();
+    // Read full-resolution pixels; resizing the desktop first loses window detail.
+    const screen = native.takeScreenshot(undefined, undefined, 0, undefined, undefined);
+    if (!screen.base64)
+        throw new Error("Desktop screen capture returned no image.");
+    const left = Math.round(bounds.x * screen.width / display.width);
+    const top = Math.round(bounds.y * screen.height / display.height);
+    const width = Math.round(bounds.width * screen.width / display.width);
+    const height = Math.round(bounds.height * screen.height / display.height);
+    const visibleLeft = Math.max(0, left);
+    const visibleTop = Math.max(0, top);
+    const visibleRight = Math.min(screen.width, left + width);
+    const visibleBottom = Math.min(screen.height, top + height);
+    if (visibleRight <= visibleLeft || visibleBottom <= visibleTop) {
+        throw new Error("The window must overlap the primary display for Windows screen capture.");
+    }
+    let image = sharp(Buffer.from(screen.base64, "base64")).extract({
+        left: visibleLeft,
+        top: visibleTop,
+        width: visibleRight - visibleLeft,
+        height: visibleBottom - visibleTop,
+    });
+    if (visibleLeft !== left || visibleTop !== top || visibleRight !== left + width || visibleBottom !== top + height) {
+        image = image.extend({
+            left: visibleLeft - left,
+            top: visibleTop - top,
+            right: left + width - visibleRight,
+            bottom: top + height - visibleBottom,
+            background: "black",
+        });
+    }
+    // Materialize the crop and padding before resize (Sharp can reorder operations).
+    const cropped = await image.png().toBuffer();
+    const { data, info } = await sharp(cropped)
+        .resize({ width: SCREENSHOT_WIDTH, withoutEnlargement: true })
+        .png().toBuffer({ resolveWithObject: true });
+    return { data: data.toString("base64"), width: info.width, height: info.height };
+}
 function sameBounds(left, right) {
     return left && right && left.x === right.x && left.y === right.y && left.width === right.width && left.height === right.height;
 }
@@ -63,7 +116,7 @@ async function createLibraryClient() {
     ]);
     return connectInProcess(createComputerUseServer({ profile: "ax", vision: true }));
 }
-async function loadAccessibilityDriver() {
+async function loadNativeDriver() {
     const { loadNative } = await import("@zavora-ai/computer-use-mcp/host-native");
     return loadNative();
 }
@@ -183,9 +236,9 @@ function normalizeShortcut(keys, platform) {
     return keys.map((key) => aliases[String(key).toUpperCase()] || String(key).toLowerCase()).join("+");
 }
 /**
- * @param {{ app?: string, windowId?: number | null, excludePids?: number[], platform?: string, inputMode?: "accessibility" | "physical", client?: any, accessibility?: any }} options
+ * @param {{ app?: string, windowId?: number | null, excludePids?: number[], platform?: string, inputMode?: "accessibility" | "physical", focusOnConnect?: boolean, client?: any, accessibility?: any, visibleBoundsReader?: typeof getWindowsVisibleBounds }} options
  */
-export async function createDesktopController({ app: requestedApp, windowId: requestedWindowId = null, excludePids = [], platform = process.platform, inputMode = "accessibility", client: injectedClient = null, accessibility: injectedAccessibility = null, } = {}) {
+export async function createDesktopController({ app: requestedApp, windowId: requestedWindowId = null, excludePids = [], platform = process.platform, inputMode = "accessibility", focusOnConnect = false, client: injectedClient = null, accessibility: injectedAccessibility = null, visibleBoundsReader = getWindowsVisibleBounds, } = {}) {
     if (!SUPPORTED_PLATFORMS.has(platform)) {
         throw new Error("Desktop control is currently supported only on macOS and Windows.");
     }
@@ -201,59 +254,91 @@ export async function createDesktopController({ app: requestedApp, windowId: req
         let targetWindow = chooseWindow(windows, requestedWindowId == null ? null : Number(requestedWindowId));
         let capture = null;
         let deviceInfo = null;
-        let accessibility = injectedAccessibility;
+        let native = injectedAccessibility;
+        let lastVisibleBounds = null;
+        let fallbackLogged = false;
         async function getWindow() {
             return parseJsonResult(await client.getWindow(targetWindow.windowId), "Window lookup");
         }
-        async function screenshot() {
-            let window;
-            let result;
+        async function focus() {
+            const activation = parseJsonResult(await client.activateWindow(targetWindow.windowId, 2000), "Window activation");
+            const focused = await getWindow();
+            if (!activation.activated || !focused.isFocused) {
+                throw new Error("Droid could not focus the selected desktop window, so no input was sent.");
+            }
+        }
+        async function captureFromDesktop(window) {
+            if (!window.isFocused) {
+                if (inputMode !== "physical") {
+                    throw new Error("Windows desktop capture requires the target window to be visible and focused. Bring it to the foreground and retry.");
+                }
+                await focus();
+                window = await getWindow();
+            }
+            native ||= await loadNativeDriver();
+            if (lastVisibleBounds?.windowId !== targetWindow.windowId || !sameBounds(lastVisibleBounds.outer, window.bounds)) {
+                lastVisibleBounds = {
+                    windowId: targetWindow.windowId,
+                    outer: { ...window.bounds },
+                    visible: await visibleBoundsReader(targetWindow.windowId, window.bounds),
+                };
+            }
+            const actionBounds = lastVisibleBounds.visible;
+            const image = await captureWindowFromDesktop(native, actionBounds);
+            if (!fallbackLogged) {
+                console.warn("Windows window capture returned all-black pixels; using a visible-desktop crop. Keep the target unobstructed on the primary display.");
+                fallbackLogged = true;
+            }
+            return { ...image, bounds: { ...window.bounds }, actionBounds: { ...actionBounds } };
+        }
+        async function screenshot({ allowDesktopFallback = true } = {}) {
             try {
                 const currentWindows = readWindows(await client.listWindows(application.bundleId));
                 const focusedWindow = currentWindows.find((candidate) => candidate.isFocused && candidate.isOnScreen);
                 if (focusedWindow)
                     targetWindow = focusedWindow;
-                window = await getWindow();
+                const window = await getWindow();
                 if (!window.isOnScreen)
                     throw new Error("The selected desktop window is no longer visible.");
-                result = await client.screenshot({
+                const result = await client.screenshot({
                     width: SCREENSHOT_WIDTH,
                     quality: 0,
                     target_window_id: targetWindow.windowId,
                 });
                 assertResult(result, "Desktop screenshot");
+                let image = { ...readScreenshot(result), bounds: { ...window.bounds }, actionBounds: { ...window.bounds } };
+                if (allowDesktopFallback && platform === "win32" && await isBlackScreenshot(image.data)) {
+                    image = await captureFromDesktop(window);
+                }
+                capture = {
+                    bounds: image.bounds,
+                    actionBounds: image.actionBounds,
+                    width: image.width,
+                    height: image.height,
+                    contentBounds: getScreenshotContentBounds(image.width, image.height, image.bounds, platform),
+                };
+                if (deviceInfo) {
+                    deviceInfo.device_width = image.actionBounds.width;
+                    deviceInfo.device_height = image.actionBounds.height;
+                    deviceInfo.scaled_width = image.width;
+                    deviceInfo.scaled_height = image.height;
+                    deviceInfo.scale = image.width / image.actionBounds.width;
+                    deviceInfo.desktopWindowId = targetWindow.windowId;
+                }
+                return image.data;
             }
             catch (error) {
                 throw new Error(formatPermissionError(error, platform));
             }
-            const image = result.content?.find((item) => item.type === "image");
-            const sizeText = result.content?.find((item) => item.type === "text")?.text || "";
-            const size = /^(\d+)x(\d+)$/.exec(sizeText.trim());
-            if (!image?.data || !size)
-                throw new Error("Desktop screenshot returned no image or dimensions.");
-            capture = {
-                bounds: { ...window.bounds },
-                width: Number(size[1]),
-                height: Number(size[2]),
-            };
-            capture.contentBounds = getScreenshotContentBounds(capture.width, capture.height, window.bounds, platform);
-            if (deviceInfo) {
-                deviceInfo.device_width = window.bounds.width;
-                deviceInfo.device_height = window.bounds.height;
-                deviceInfo.scaled_width = capture.width;
-                deviceInfo.scaled_height = capture.height;
-                deviceInfo.scale = capture.width / window.bounds.width;
-                deviceInfo.desktopWindowId = targetWindow.windowId;
-            }
-            return image.data;
         }
         function scaledPoint(x, y) {
             if (!capture)
                 throw new Error("Capture the desktop window before executing an action.");
             const content = capture.contentBounds;
+            const bounds = capture.actionBounds;
             return [
-                Math.round(capture.bounds.x + ((x - content.x) * capture.bounds.width) / content.width),
-                Math.round(capture.bounds.y + ((y - content.y) * capture.bounds.height) / content.height),
+                Math.round(bounds.x + ((x - content.x) * bounds.width) / content.width),
+                Math.round(bounds.y + ((y - content.y) * bounds.height) / content.height),
             ];
         }
         async function prepareAction(requireFocus) {
@@ -265,11 +350,7 @@ export async function createDesktopController({ app: requestedApp, windowId: req
             }
             if (!requireFocus)
                 return;
-            const activation = parseJsonResult(await client.activateWindow(targetWindow.windowId, 2000), "Window activation");
-            const focused = await getWindow();
-            if (!activation.activated || !focused.isFocused) {
-                throw new Error("Droid could not focus the selected desktop window, so no input was sent.");
-            }
+            await focus();
         }
         const targetOptions = () => ({ targetWindowId: targetWindow.windowId, focusStrategy: "strict" });
         async function performCursorFreeAction(actionType, x, y, direction = null) {
@@ -277,8 +358,8 @@ export async function createDesktopController({ app: requestedApp, windowId: req
             const selected = chooseAccessibilityElement(tree, x, y, actionType, direction);
             if (!selected)
                 throw new Error(cursorFreeError(actionType));
-            accessibility ||= await loadAccessibilityDriver();
-            const result = accessibility.performAction(targetWindow.windowId, selected.element.role, selected.element.label, selected.action);
+            native ||= await loadNativeDriver();
+            const result = native.performAction(targetWindow.windowId, selected.element.role, selected.element.label, selected.action);
             if (!result?.performed)
                 throw new Error(`${cursorFreeError(actionType)}${result?.reason ? ` Reason: ${result.reason}.` : ""}`);
         }
@@ -375,16 +456,19 @@ export async function createDesktopController({ app: requestedApp, windowId: req
                 return { success: false, error: message };
             }
         }
-        await screenshot();
+        if (focusOnConnect)
+            await focus();
+        // Without focus, connection only probes the window; the desktop may be covered.
+        await screenshot({ allowDesktopFallback: focusOnConnect });
         deviceInfo = {
             platform: "desktop",
             source: "local",
             device_name: `${application.displayName} — ${targetWindow.title || "Untitled"}`,
-            device_width: targetWindow.bounds.width,
-            device_height: targetWindow.bounds.height,
+            device_width: capture.actionBounds.width,
+            device_height: capture.actionBounds.height,
             scaled_width: capture.width,
             scaled_height: capture.height,
-            scale: capture.width / targetWindow.bounds.width,
+            scale: capture.width / capture.actionBounds.width,
             desktopAppId: application.bundleId,
             desktopWindowId: targetWindow.windowId,
             desktopInputMode: inputMode,
@@ -394,7 +478,8 @@ export async function createDesktopController({ app: requestedApp, windowId: req
             window: targetWindow,
             deviceId: `desktop:${targetWindow.windowId}`,
             deviceInfo,
-            getScreenshotAsBase64: screenshot,
+            focus,
+            getScreenshotAsBase64: () => screenshot(),
             handleModelAction: handleAction,
             close: () => client.close(),
         };

package/build/src/desktop/windows-visible-bounds.js

@@ -0,0 +1,55 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const runFile = promisify(execFile);
+const RECT_SCRIPT = `
+Add-Type -TypeDefinition @'
+using System;
+using System.Runtime.InteropServices;
+public static class WindowFrame {
+  public const int DWMWA_EXTENDED_FRAME_BOUNDS = 9;
+  [StructLayout(LayoutKind.Sequential)] public struct Rect { public int Left; public int Top; public int Right; public int Bottom; }
+  [DllImport("user32.dll")] public static extern bool GetWindowRect(IntPtr handle, out Rect rect);
+  [DllImport("dwmapi.dll")] public static extern int DwmGetWindowAttribute(IntPtr handle, int attribute, out Rect rect, int size);
+}
+'@
+$handle = [IntPtr]::new([long]WINDOW_ID)
+$outer = [WindowFrame+Rect]::new()
+$visible = [WindowFrame+Rect]::new()
+if (-not [WindowFrame]::GetWindowRect($handle, [ref]$outer)) { exit 1 }
+$result = [WindowFrame]::DwmGetWindowAttribute($handle, [WindowFrame]::DWMWA_EXTENDED_FRAME_BOUNDS, [ref]$visible, 16)
+if ($result -ne 0) { exit 1 }
+@($outer.Left, $outer.Top, $outer.Right, $outer.Bottom, $visible.Left, $visible.Top, $visible.Right, $visible.Bottom) -join ','
+`;
+export async function getWindowsVisibleBounds(windowId, bounds) {
+    if (process.platform !== "win32")
+        return bounds;
+    if (!Number.isSafeInteger(windowId))
+        return bounds;
+    try {
+        // GetWindowRect includes invisible resize borders; DWM reports the pixels actually drawn.
+        const script = RECT_SCRIPT.replace("WINDOW_ID", String(windowId));
+        const { stdout } = await runFile("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], {
+            windowsHide: true,
+            timeout: 5000,
+        });
+        const [outerLeft, outerTop, outerRight, outerBottom, left, top, right, bottom] = stdout.trim().split(",").map(Number);
+        const scaleX = bounds.width / (outerRight - outerLeft);
+        const scaleY = bounds.height / (outerBottom - outerTop);
+        const insetLeft = Math.round((left - outerLeft) * scaleX);
+        const insetTop = Math.round((top - outerTop) * scaleY);
+        const insetRight = Math.round((outerRight - right) * scaleX);
+        const insetBottom = Math.round((outerBottom - bottom) * scaleY);
+        if (![insetLeft, insetTop, insetRight, insetBottom].every((value) => Number.isFinite(value) && value >= 0)) {
+            throw new Error("Invalid window frame insets.");
+        }
+        const width = bounds.width - insetLeft - insetRight;
+        const height = bounds.height - insetTop - insetBottom;
+        if (width <= 0 || height <= 0)
+            throw new Error("Invalid visible window dimensions.");
+        return { x: bounds.x + insetLeft, y: bounds.y + insetTop, width, height };
+    }
+    catch {
+        console.warn("Windows visible-frame lookup failed; using outer window bounds, which may include invisible resize borders.");
+        return bounds;
+    }
+}

package/build/src/integrations/loadmill/report-upload-manager.js

@@ -1,8 +1,10 @@
 import { createHash, randomUUID } from "node:crypto";
+import { findDeepestErrorCode } from "../../utils/error-details.js";
 export const MAX_SCREENSHOTS_PER_REPORT = 1000;
 export const MAX_REPORT_OBJECT_BYTES = 10 * 1024 * 1024;
-function warn(session, message) {
+function warn(session, message, phase) {
     session.failed = true;
+    session.onFailure?.({ uploadId: session.uploadId, phase, objectName: null, httpStatus: null, errorName: "ValidationError", errorCode: null });
     session.onWarning?.(message);
 }
 function getHttpStatus(error) {
@@ -16,6 +18,20 @@ function warnAboutUploadFailure(session) {
     const status = session.uploadFailureStatus ? ` (HTTP ${session.uploadFailureStatus})` : "";
     session.onWarning?.(`Cloud report upload failed${status}; further uploads skipped.`);
 }
+function recordFailure(session, phase, objectName, error) {
+    if (session.uploadFailed)
+        return;
+    session.uploadFailed = true;
+    session.uploadFailureStatus = getHttpStatus(error);
+    session.onFailure?.({
+        uploadId: session.uploadId,
+        phase,
+        objectName,
+        httpStatus: session.uploadFailureStatus,
+        errorName: error instanceof Error ? error.name : typeof error,
+        errorCode: findDeepestErrorCode(error),
+    });
+}
 function decodeScreenshot(dataUrl) {
     const match = /^data:image\/png;base64,([a-zA-Z0-9+/=\s]+)$/.exec(dataUrl);
     return match ? Buffer.from(match[1], "base64") : null;
@@ -46,13 +62,15 @@ export class DroidReportUploadManager {
      *     associateDroidRunReport: (runId: string, payload: object) => Promise<unknown>,
      *   },
      *   onWarning?: ((message: string) => void) | null,
+     *   onFailure?: ((details: { uploadId: string, phase: string, objectName: string | null, httpStatus: string | null, errorName: string, errorCode: string | null }) => void) | null,
      * }} options
      */
-    startSession({ loadmillClient, onWarning = null } = {}) {
+    startSession({ loadmillClient, onWarning = null, onFailure = null } = {}) {
         const session = {
             uploadId: randomUUID(),
             loadmillClient,
             onWarning,
+            onFailure,
             sequence: 0,
             screenshotCount: 0,
             lastScreenshotObjectName: null,
@@ -79,15 +97,15 @@ export class DroidReportUploadManager {
         }
         const body = decodeScreenshot(dataUrl);
         if (!body) {
-            warn(session, "Failed to upload Droid report screenshot: unsupported image data.");
+            warn(session, "Failed to upload Droid report screenshot: unsupported image data.", "validate_screenshot");
             return null;
         }
         if (body.length > MAX_REPORT_OBJECT_BYTES) {
-            warn(session, `Droid report screenshot exceeds ${MAX_REPORT_OBJECT_BYTES} bytes.`);
+            warn(session, `Droid report screenshot exceeds ${MAX_REPORT_OBJECT_BYTES} bytes.`, "validate_screenshot");
             return null;
         }
         if (session.screenshotCount >= MAX_SCREENSHOTS_PER_REPORT) {
-            warn(session, `Droid report exceeds ${MAX_SCREENSHOTS_PER_REPORT} screenshots.`);
+            warn(session, `Droid report exceeds ${MAX_SCREENSHOTS_PER_REPORT} screenshots.`, "validate_screenshot");
             return null;
         }
         const name = `screenshots/${String(++session.sequence).padStart(4, "0")}.png`;
@@ -107,7 +125,16 @@ export class DroidReportUploadManager {
         session.finishing = true;
         session.finishPromise = this.#finish(session, { savedRunId, html }).catch((error) => {
             const status = getHttpStatus(error);
-            warn(session, `Failed to publish Droid run report${status ? ` (HTTP ${status})` : ""}.`);
+            session.onFailure?.({
+                uploadId: session.uploadId,
+                phase: "associate_report",
+                objectName: null,
+                httpStatus: status,
+                errorName: error instanceof Error ? error.name : typeof error,
+                errorCode: findDeepestErrorCode(error),
+            });
+            session.failed = true;
+            session.onWarning?.(`Failed to publish Droid run report${status ? ` (HTTP ${status})` : ""}.`);
             return { published: false, reason: "publish_failed" };
         }).finally(() => {
             this.sessions.delete(session);
@@ -125,7 +152,7 @@ export class DroidReportUploadManager {
         }
         const body = Buffer.from(html, "utf8");
         if (body.length > MAX_REPORT_OBJECT_BYTES) {
-            warn(session, `Droid HTML report exceeds ${MAX_REPORT_OBJECT_BYTES} bytes.`);
+            warn(session, `Droid HTML report exceeds ${MAX_REPORT_OBJECT_BYTES} bytes.`, "validate_report");
             return { published: false, reason: "too_large" };
         }
         const htmlUpload = await this.#enqueue(session, {
@@ -198,6 +225,7 @@ export class DroidReportUploadManager {
     }
     async #runTask(task) {
         let result = { uploaded: false, key: null };
+        let phase = "request_policy";
         try {
             if (task.session.uploadFailed) {
                 return;
@@ -207,13 +235,13 @@ export class DroidReportUploadManager {
             if (!uploadPolicy?.key) {
                 throw new Error("Loadmill did not return an upload policy.");
             }
+            phase = "upload_object";
             await uploadObject(uploadPolicy, task.object.body, task.object.name.split("/").at(-1), task.object.contentType, this.fetchImpl);
             result = { uploaded: true, key: uploadPolicy.key };
         }
         catch (error) {
             task.session.failed = true;
-            task.session.uploadFailed = true;
-            task.session.uploadFailureStatus ??= getHttpStatus(error);
+            recordFailure(task.session, phase, task.object.name, error);
         }
         finally {
             task.session.pending.delete(task.promise);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loadmill/droid-cua",
-  "version": "2.39.0",
+  "version": "2.40.0",
   "description": "AI-powered Android testing agent using OpenAI's computer-use model and ADB",
   "main": "build/index.js",
   "type": "module",

package/skill/droid-cua/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: droid-cua
 description: Operate and improve Droid CUA `.dcua` test projects. Use when the user explicitly names Droid CUA or @loadmill/droid-cua, or asks to author, configure, run, diagnose, heal, stabilize, or speed up `.dcua` tests with the Droid CUA CLI or desktop app. Do not use for general web browsing, website development, browser automation, generic mobile work, or non-Droid test tasks.
+metadata:
+  version: "1.0.8"
 ---
 
 # Droid CUA
@@ -12,7 +14,7 @@ Use the existing `droid-cua` CLI and repository files. Do not invent commands, f
 1. Inspect the active test project before creating files. Find existing `.dcua` tests, `context.md`, `test-data.md`, `.secrets`, `.env`, and `ci/droid-cua.json` without reading secret values. Do not search other projects or the user's home directory for credentials.
 2. Determine the requested platform and target from the task or project. Ask the user only when the choice is unclear.
 3. Check authentication and environment readiness before the first run. Read [project-and-auth.md](references/project-and-auth.md) for project boundaries and token handling. Read [onboarding-and-troubleshooting.md](references/onboarding-and-troubleshooting.md) when setup, dependency, device, simulator, browser, or connection work is needed.
-4. Author or update the smallest useful test. Read [authoring-tests.md](references/authoring-tests.md) before changing `.dcua`, context, test data, secrets, or config.
+4. Identify the intended coverage, starting state, scenario inputs, and cleanup; author or update the smallest useful test that preserves them. Read [authoring-tests.md](references/authoring-tests.md) before changing `.dcua`, context, test data, secrets, or config.
 5. Before execution, present the proposed tests and target to the user, resolve any questions, and get their confirmation. Read [running-and-healing.md](references/running-and-healing.md) for the required pre-run check.
 6. Run the confirmed, narrowest relevant test and monitor it to completion. Keep the user oriented during the run by surfacing meaningful live screenshots, not just terminal output.
 7. For a new, changed, flaky, slow, or explicitly optimized test, continue with the evidence-driven author-run-improve loop in [iterative-improvement.md](references/iterative-improvement.md). A passing run is a baseline, not proof of readiness.
@@ -27,7 +29,7 @@ Use the existing `droid-cua` CLI and repository files. Do not invent commands, f
 - Get approval before installing dependencies, running `sudo`, accepting licenses, or changing system configuration.
 - During setup, do not create or edit user tests. Rerun only the failed readiness check, then resume the original task.
 - During healing, edit only `.dcua`, `context.md`, `test-data.md`, or Droid CUA config. Never modify application code under the guise of healing a test.
-- Never weaken or remove an assertion merely to make a failing run pass.
+- Never weaken required coverage or remove an assertion merely to make a failing run pass. Agent-added, out-of-scope assertions may be removed only with a coverage-based explanation; see [authoring-tests.md](references/authoring-tests.md).
 - Keep one canonical context file and one canonical Droid CUA config file per test project. Reuse and update those shared files; never create test-specific context or config copies for a new or improved test.
 - When improving an existing test, keep its complete flow in one independently runnable `.dcua` file. Do not split it into ordered or state-dependent tests as an optimization; Droid CUA does not currently guarantee that separate tests will run consecutively or share state.
 - Before rerunning a long test, apply the smallest evidence-supported batch that addresses its known bottlenecks. The batch may include multiple `.dcua`, context, test-data, or config improvements when each has a clear rationale and preserves coverage. Record the complete change set; isolate or revert individual changes only if the combined result regresses or remains ambiguous.
@@ -39,7 +41,7 @@ Use the existing `droid-cua` CLI and repository files. Do not invent commands, f
 
 - Prefer an existing project convention over creating a parallel structure.
 - Prefer headless runs for agent work because they are observable and return deterministic exit codes.
-- Write tests as concise, human-readable user journeys. Prefer one business-level instruction per user goal over one instruction per tap, menu, dialog, or other UI gesture; add lower-level guidance only when run evidence shows it is necessary.
+- Preserve the user's intended coverage. Write one readable micro-goal per step: a small user task with a recognizable completion point. During improvement, simplify before adding detail, and retain only detail that is necessary and supported by evidence. Do not optimize for fewer lines or compress several goals into one instruction.
 - Use explicit, user-observable outcomes in tests rather than implementation details or coordinates.
 - Diagnose the first divergence between the instruction and observed behavior before changing anything.
 - Compare runs on the same target and app build, and clearly identify every test, context, data, model, or config change included in the optimization batch.

package/skill/droid-cua/references/authoring-tests.md

@@ -4,32 +4,91 @@
 
 Find nearby `.dcua` tests and project files before writing. Match their directory layout, naming, vocabulary, starting state, and config conventions. Do not open `.env` or `.secrets`.
 
+## Establish intended coverage
+
+Before drafting or healing, identify the requested behavior, starting state, scenario inputs, business outcome, and cleanup from the user request and existing test. Keep this brief in the working plan; no separate specification file is required. Distinguish user-required checks from incidental checks introduced during earlier agent iterations. If an existing assertion's purpose is unclear, preserve it until its scope is resolved.
+
+Preserve scenario choices during simplification: a full-day booking and a three-hour booking exercise different behavior. Adding UI cancellation also changes coverage; do it when requested, not automatically for every creation test.
+
+Prefer predictable setup and data over conditional recovery. Use known cleanup and simple relative dates when appropriate for the project. A date such as next Monday assumes a working day and available account state; establish those assumptions rather than inventing a search for the earliest conflict-free date. Restarting the app is a project-specific starting condition, not a universal requirement. Include only setup needed by this scenario and supported by the request, project knowledge, or observed behavior. Do not import dates, reset flows, or other prerequisites from a nearby example just because they made that example runnable. If an unknown prerequisite matters, identify the gap rather than silently inventing a mandatory step.
+
 ## Write `.dcua` instructions
 
-- Put one clear user goal or assertion on each non-empty line. One instruction does not need to equal one UI action.
-- Write concise, human-readable business or journey instructions that describe what the user wants to accomplish. Prefer `Select the desired date` or `Log out` over separate instructions for opening a picker or menu, clicking controls, handling an expected confirmation, and submitting.
-- Do not prescribe coordinates, selectors, implementation details, model strategy, or every tap and keystroke. These micro-steps couple the test to incidental UI structure, add model rounds, and make harmless UI changes more likely to break it.
-- Break a business-level instruction into smaller actions only when run evidence shows that the agent cannot complete it reliably or the intermediate state is itself behavior the test must verify.
-- State the starting condition when it is not guaranteed by the environment.
-- Use explicit assertions for important outcomes. Prefer stable visible facts such as a screen title, confirmation message, changed value, or navigation result.
-- Use exact visible labels when naming controls or outcomes.
+- Put one readable micro-goal on each non-empty line: a small user task with a recognizable completion point, such as choosing a room, selecting dates, or submitting a request. One goal can require several UI actions.
+- Keep useful task boundaries. Do not compress login, navigation, data entry, and verification into a single instruction to reduce the line count.
+- Specify the scenario choices precisely while leaving ordinary UI mechanics to Droid. Avoid coordinates, selectors, icon appearance, and instructions for every tap or keystroke.
+- Use visible labels when they identify a meaningful choice or resolve ambiguity. Short navigation hints are welcome when useful, such as `Custom duration (scroll right in the duration options)`; do not require exact layout or incidental copy.
+- Add lower-level guidance only when evidence shows it is necessary to complete the goal reliably, or the intermediate behavior is explicitly under test. Prefer clarifying the goal over appending a transcript of a failed run.
 - Keep each new test focused on one behavior. Separate unrelated flows only when each resulting test is fully independent and does not rely on execution order or state created by another test.
-- When updating or optimizing an existing test, preserve its complete flow in one `.dcua` file. Do not split it into sequential or dependent tests unless the user explicitly requests that structure and the project has a verified orchestration mechanism that guarantees ordering and shared state.
-- Use `//` comments sparingly for human context; comments are not executed.
-- Never include secret values in the test.
+- When updating or optimizing an existing test, preserve its complete intended flow in one independently runnable `.dcua` file. Do not split it into sequential or dependent tests without explicit user direction and verified orchestration.
+- Use `//` comments sparingly for human context; comments are not executed. Never include secret values.
+
+## Choose assertions by coverage
+
+Ask: **If this check failed while the requested business outcome remained correct, would that be a defect this scenario is intended to catch?** If not, it generally should not be a standalone assertion here. Droid must observe intermediate states to perform actions; those observations do not all need to become test assertions.
+
+Verify meaningful outcomes and identify the created or changed object by the relevant scenario inputs. Checking that the request for the selected room, dates, and duration is confirmed prevents an unrelated approved request from satisfying the test. Do not automatically assert every dialog closure, available option, summary label, or absence of a warning when the final outcome already covers the intended behavior.
+
+Preserve explicit user requirements and genuine product failures. Remove an agent-added assertion only when it is demonstrably outside intended coverage or redundant with a retained check; explain that coverage-based reason, not merely that it failed or cost time. An intermediate control or exact message still needs an assertion when that behavior is the requested subject of the test.
+
+## Example: readable booking journeys
+
+These examples use a fictional room-booking app, generic test accounts, and invented flow and control names. They do not describe a customer's product. Assume the project maps the test account to configured secret keys and the named cleanup flow makes the sample room available. This hypothetical user explicitly wants a fresh app start and UI cancellation coverage. Adapt those choices to the actual project; neither is a universal requirement.
+
+Full-day booking:
+
+```text
+Run the Loadmill "Reset sample room bookings" flow.
+Open the booking app; if already open, fully close it and reopen it.
+Log in as the test member, logging out first if another user is signed in.
+Go to Home.
+Start a room booking.
+Choose "Sample room".
+Select next Monday–Tuesday as full days.
+Submit the booking.
+Go to My bookings.
+Verify the new booking for Sample room and the selected dates is confirmed for 2 full days.
+Open that booking and cancel it through its menu.
+Verify that booking no longer appears in My bookings.
+```
+
+Custom-duration booking:
+
+```text
+Run the Loadmill "Reset sample room bookings" flow.
+Open the booking app; if already open, fully close it and reopen it.
+Log in as the test member, logging out first if another user is signed in.
+Go to Home.
+Start a room booking.
+Choose "Sample room".
+Select next Monday at 09:00.
+Choose "Custom duration" (scroll right in the duration options) and set 3 hours.
+Submit the booking.
+Go to My bookings.
+Verify the new booking for Sample room on the selected date at 09:00 is confirmed for 3 hours.
+Open that booking and cancel it through its menu.
+Verify that booking no longer appears in My bookings.
+```
+
+The final assertions identify the requested result and cleanup. Neither test checks unrelated duration options or how the calendar collapses. The short scrolling hint helps find a relevant choice without scripting the entire interaction.
+
+If a run leaves the calendar selection unconfirmed, first clarify `Select next Monday–Tuesday as full days` to `Select next Monday–Tuesday as full days and confirm the date selection.` Avoid accumulating instructions such as “tap Apply now even if the total updated” plus assertions that the grid and button disappear. Verify that the clearer goal resolves the observed failure; retain a specific control hint only if it is still needed. Do not hide an unresolved Droid or product defect in test prose.
+
+## Example: account preferences
 
-Example:
+This fictional settings app illustrates the same approach without booking dates, cleanup flows, or app restarts. The requested behavior is saving a notification preference and retaining it when settings are reopened; assume the test account initially uses Daily notifications.
 
 ```text
-Sign in using the USER_EMAIL and USER_PASSWORD secrets.
-Assert that the Home screen is visible and shows the signed-in account.
-Select December 15 as the requested date.
-Assert that December 15 is shown as the requested date.
-Log out.
-Assert that the sign-in screen is visible.
+Log in to the settings app as the test member.
+Open Notification settings.
+Change the email digest frequency to Weekly.
+Save the preferences.
+Leave Notification settings and reopen it.
+Verify the email digest frequency is still Weekly.
+Restore the email digest frequency to Daily and save.
 ```
 
-Keep meaningful outcomes explicit even when actions are high-level. For example, follow `Log out` with an assertion that the sign-in screen is visible when logout behavior is under test.
+The persistence check protects the requested behavior. Checking a toast, button color, or menu animation would add unrelated requirements. Restore the known starting value for repeatability; do not invent cleanup when the scenario or environment does not need it.
 
 Use the secret key names that exist in `.secrets`; do not inspect their values. If key discovery is necessary, filter the file so only keys reach output, for example `sed -n 's/^\([^#][^=]*\)=.*/\1/p' .secrets`. If a required key is absent, ask the user to add it without sharing its value.
 

package/skill/droid-cua/references/iterative-improvement.md

@@ -10,7 +10,7 @@ One confirmation may cover that iterative workflow. Continue without asking agai
 
 ## 2. Establish a reproducible baseline
 
-Run the narrowest test with its existing project model and config. Keep these fixed for the baseline, then change any of them only as part of a documented, evidence-supported optimization batch:
+Record the intended coverage using [authoring-tests.md](authoring-tests.md) before editing, including which assertions are user requirements. Run the narrowest test with its existing project model and config. Keep these fixed for the baseline, then change any of them only as part of a documented, evidence-supported optimization batch:
 
 - App build and initial account/data state.
 - Device, OS, device source, or browser session mode.
@@ -49,18 +49,18 @@ Stop healing when evidence indicates an application regression. Preserve the fai
 For long-running tests, fix all well-supported bottlenecks that can be addressed safely before paying for another full run. Use this order to build the batch unless evidence points elsewhere:
 
 1. **`.dcua` wording and scope**
-   - Express one human-readable business goal per instruction, not one click, menu, field, dialog, or submit action per line.
+   - Express one readable micro-goal per instruction. Choosing a room, selecting dates, and submitting a booking are useful separate goals; opening each menu or tapping each control usually is not.
    - Collapse consecutive micro-steps into the user outcome they jointly accomplish, such as `Select the desired date` or `Log out`, while keeping meaningful assertions explicit.
    - Use exact visible labels only when they disambiguate the goal or identify an outcome the test must verify.
-   - Add the missing starting condition or assertion at the first ambiguous transition.
+   - Resolve an ambiguous transition by checking the starting state, data, and wording first. Add an assertion only when it protects intended coverage; observing progress does not require a new test assertion.
    - Remove scenario steps that do not protect the behavior under test.
-   - Add lower-level actions only when the evidence shows the business-level instruction is unreliable or an intermediate state is part of the coverage.
+   - Rewrite the unclear goal before adding lower-level actions. Add a short hint only when the evidence shows it is still necessary or an intermediate state is part of the coverage; do not append emphatic commands and UI-state checks from each failed run.
    - Keep the existing scenario in one independently runnable `.dcua` file. Splitting a long test into ordered or state-dependent tests is not an available optimization because separate execution order and shared state are not guaranteed.
-   - Never remove or weaken a meaningful assertion to obtain a pass.
+   - Preserve required assertions and scenario choices. Remove agent-added, out-of-scope or redundant assertions only with the coverage-based explanation required by the authoring guide; preserve checks whose purpose is unresolved.
 
 2. **`context.md`**
    - Update the project's existing canonical context file; never create a test-specific context file for the optimization.
-   - Add durable product navigation, terminology, stable interruptions, and narrowly observed recovery behavior.
+   - Add durable product navigation, terminology, and stable interruptions. Do not move accumulated scenario recovery instructions into shared context to make the test appear simpler.
    - Move reusable mechanics out of the test, but keep scenario-specific values and expectations in the test.
    - Remove redundant, speculative, or conflicting instructions. Do not restate Droid's base behavior or encode a workaround for a Droid/product bug as product knowledge.
 
@@ -114,11 +114,14 @@ For every included change, record the evidence, rationale, expected effect, and
 
 ## 6. Compare and iterate
 
+After each edit, reread the whole test against its intended coverage. Remove superseded hints and redundant checks, keep one micro-goal per instruction, and ensure setup or data problems have not become speculative recovery branches. Keep diagnostic history in the report, not the test or shared context. Validate the simplified version in the next representative run.
+
 After each rerun, compare:
 
 - Did the first divergence disappear for the expected reason?
 - Did the hotspot's duration, rounds, actions, previews, retries, or recoveries improve?
 - Did another step regress or did coverage change?
+- Did the test become harder to read or more dependent on incidental UI details? Explain any retained complexity by coverage or execution evidence; fewer lines alone are not an improvement.
 - Did the combined change set improve the intended hotspots without obscuring a regression?
 
 Keep the batch when the evidence supports the overall result. If it regresses or remains ambiguous, use the timeline to isolate, revise, or revert only the suspect subset instead of automatically rerunning every change separately. Continue while the evidence supports another useful test, context, data, or configuration improvement. Stop and report the strongest remaining explanation only when a genuine blocker remains or no evidence-supported improvement is left to try.
@@ -129,6 +132,7 @@ After the optimized test passes, decide whether the accumulated evidence is stro
 
 Call the test ship-ready only when:
 
+- The final test still expresses the intended coverage as readable micro-goals, with no unnecessary assertions, stale debugging instructions, or speculative recovery branches.
 - All intended instructions and meaningful assertions pass in the final representative evidence.
 - No unexplained recovery, repeated-action loop, or recurring high-risk hotspot remains.
 - Timing and action counts are reasonably consistent, with transient provider retries identified separately.

package/skill/droid-cua/references/onboarding-and-troubleshooting.md

@@ -4,6 +4,12 @@ Follow the Desktop Device Setup Wizard sequence: choose a platform, run checks,
 
 Do not create or modify user test files merely to perform setup. Get approval before installing software, changing system configuration, running `sudo`, or accepting a license. After remediation, rerun only the failed check.
 
+## Identify the installed skill
+
+When diagnosing skill behavior, report the installed skill version and bundled skill version from `droid-cua skill status <agent>` (`cursor`, `claude-code`, or `codex`). Use `--local` for a project installation. The skill's own version is `metadata.version` in `SKILL.md`; it is independent of the CLI package version. If an older CLI does not display versions, read this field from the active skill copy instead.
+
+`unknown` means version metadata is unavailable, as with older copies. `modified` means the installed files differ from the bundled skill; it can indicate an older release or local edits, including edits that left the version unchanged. Report that state alongside the version. Updating the CLI does not update existing skill copies; explain any mismatch before using `droid-cua skill install <agent> --force`, which overwrites local changes.
+
 ## Droid CUA CLI compatibility
 
 If the CLI rejects a model, option, command, or capability that this skill explicitly documents, treat an outdated global `@loadmill/droid-cua` package as a likely setup issue. Do not suggest an update for an ordinary test, target, provider, or application failure.

package/skill/droid-cua/references/project-and-auth.md

@@ -40,4 +40,4 @@ Offer exactly these two choices, then wait for the user's selection:
 
 Use a secret-safe mechanism that does not print or expose the value in commands, logs, or responses. Verify only that the key is present. Never copy a token from another file, a shell profile, another project, an agent skill/configuration, or any other location. Do not inspect inherited environment variables to discover a token. When the active project's `.env` contains the key, run `droid-cua` normally from that project; the CLI loads that file automatically.
 
-Only when the user explicitly selects direct OpenAI access, use `--llm-provider openai` with one of the supported OpenAI CUA models: `gpt-5.6-terra`, `gpt-5.6-luna`, or `gpt-5.4`. Check only the active project's `.env` for `OPENAI_API_KEY`; do not use one found elsewhere. If it is missing, guide the user to create and configure their own key in the same project using the same secret-safe process. Do not silently switch providers to bypass missing Loadmill authentication.
+Only when the user explicitly selects direct OpenAI access, use `--llm-provider openai` with `gpt-6-sol` or `gpt-6-luna`. Saved direct GPT-5.6 Terra and GPT-5.4 selections migrate to GPT-6 Sol; saved GPT-5.6 Luna selections migrate to GPT-6 Luna. Check only the active project's `.env` for `OPENAI_API_KEY`; do not use one found elsewhere. If it is missing, guide the user to create and configure their own key in the same project using the same secret-safe process. Do not silently switch providers to bypass missing Loadmill authentication.

package/skill/droid-cua/references/running-and-healing.md

@@ -16,12 +16,16 @@ Preserve an existing provider/model choice in `ci/droid-cua.json`; otherwise use
 --llm-provider loadmill --cua-model loadmill-smart
 ```
 
-All Loadmill models require `LOADMILL_API_TOKEN`. Do not switch from Pulse to Smart merely because a test failed or was slow; first identify a model-related stability issue, then keep Smart only when comparison evidence shows an improvement. Do not switch between Smart, Pulse, and Beacon silently; preserve the project's model or explain the capability, speed, and experimental tradeoffs and follow the user's choice. If the user chooses direct OpenAI access instead, require `OPENAI_API_KEY` and use `--llm-provider openai` with one of `gpt-5.6-terra`, `gpt-5.6-luna`, or `gpt-5.4`. Do not mix a provider with another provider's model, silently switch providers, or override an existing project choice without explaining it.
+All Loadmill models require `LOADMILL_API_TOKEN`. Smart and Pulse now route through the Loadmill gateway to GPT-6 Sol and GPT-6 Luna. Do not switch from Pulse to Smart merely because a test failed or was slow; first identify a model-related stability issue, then keep Smart only when comparison evidence shows an improvement. Do not switch between Smart, Pulse, and Beacon silently; preserve the project's model or explain the capability, speed, and experimental tradeoffs and follow the user's choice. If the user chooses direct OpenAI access instead, require `OPENAI_API_KEY` and use `--llm-provider openai` with `gpt-6-sol` or `gpt-6-luna`. Do not mix a provider with another provider's model, silently switch providers, or override an existing project choice without explaining it.
 
 Include `--report reports/<test-name>.html` for normal test runs unless the user opts out. Prefer an explicit filename over a directory so the result is easy to locate. Add `--debug` for every agent-observed run: it writes the screenshots needed for live progress updates as well as diagnosis.
 
+For macOS and Windows desktop tests, the desktop app shows a system notice for three seconds before Droid takes control. The three-second delay is fixed; once the test starts, use Stop in Droid to end it. Avoid using the mouse or keyboard during the run. Droid brings the selected target window to the foreground before the first capture. When the run ends, the target stays in front and a second system notice says Droid has finished controlling the desktop. Open Droid to review the result. Some Windows apps return an all-black window capture; Droid brings the target back to the foreground before cropping the visible desktop to its visible frame, excluding the invisible Windows resize border. The fallback logs an all-black capture warning and crops before resizing to preserve detail. A visible-frame lookup warning means Droid is using the outer window bounds, which may include invisible resize borders. Keep the target visible and unobstructed on the primary display. In accessibility input mode, bring the target to the foreground yourself if the fallback requests it; Droid does not focus it for screenshots. If a screenshot shows another app or black off-screen edges, check whether the target could be focused and fully displayed before changing the `.dcua` instructions.
+
 When downstream automation needs an exact Loadmill handoff, add `--report-metadata reports/<test-name>.json`. Read it only after Droid exits. Droid clears the destination at run start and writes the saved run ID plus the last uploaded screenshot object name only after cloud report publication succeeds, including when a failed test's report was published. Do not infer the run or screenshot by searching recent Loadmill runs when this file was requested but absent.
 
+For desktop runs, treat the test result and dashboard report as separate outcomes. A run can appear in Droid Runs while its report is still uploading. A `report.upload.skipped` entry in the app's `desktop-events.jsonl` explains when sharing was disabled or authentication was unavailable. For failures, use the run warning and `report.upload.failed` entry, which includes the upload stage and HTTP status when available. The absence of a failure entry does not prove that a still-unavailable report was published; it may still be uploading. Direct the user to the local report in Droid when sharing did not complete. Do not infer the cause from an unclickable dashboard row alone.
+
 ```sh
 # Attached Android device or running emulator
 droid-cua run tests/example.dcua --llm-provider loadmill --cua-model loadmill-pulse --avd adb:<serial> --context tests/context.md --debug --report reports/example.html
@@ -42,7 +46,7 @@ droid-cua run tests/example.dcua --llm-provider loadmill --cua-model loadmill-pu
 droid-cua run tests/example.dcua --llm-provider loadmill --cua-model loadmill-pulse --device-source aws-device-farm --platform android --device-name "<name>" --os-version "<version>" --app <app.apk> --debug --report reports/example.html
 
 # Direct OpenAI alternative
-droid-cua run tests/example.dcua --llm-provider openai --cua-model gpt-5.4 --avd adb:<serial> --context tests/context.md --debug --report reports/example.html
+droid-cua run tests/example.dcua --llm-provider openai --cua-model gpt-6-sol --avd adb:<serial> --context tests/context.md --debug --report reports/example.html
 
 # Selected tests from different folders
 droid-cua run tests/auth/login.dcua tests/checkout/purchase.dcua admin/refund.dcua --avd adb:<serial> --config ci/droid-cua.json --debug --report reports/selected-tests.html
@@ -133,6 +137,6 @@ Keep this retrospective concise and lead with the result and improvement. Do not
 
 ## Guarded healing
 
-Before editing, state the classification and evidence. Change only `.dcua`, `context.md`, `test-data.md`, or Droid CUA config. Never edit app code, delete coverage, loosen the expected outcome, or add broad waits simply to obtain green output.
+Before editing, state the classification and evidence. Change only `.dcua`, `context.md`, `test-data.md`, or Droid CUA config. Never edit app code, delete required coverage, loosen the expected outcome, or add broad waits simply to obtain green output. Use the coverage rules in [authoring-tests.md](authoring-tests.md) to distinguish required assertions from agent-added, out-of-scope or redundant checks; retain assertions whose purpose is unclear. A failing business outcome remains a failure.
 
-Apply the smallest evidence-supported batch, explain why each change corrects the test rather than hides a product defect, and rerun only the affected test. Continue analyzing, editing, and rerunning until the final representative evidence supports readiness or a genuine blocker remains. Do not stop based on a fixed rerun count. Stop when the evidence indicates an application regression, an environment or product dependency prevents progress, or no evidence-supported test, context, data, or configuration improvement remains; report the original and final evidence, changes attempted, and recommended owner/action.
+Simplify unclear goals and check setup/data before adding UI detail. Replace obsolete guidance rather than accumulating commands from each failed run, and review the whole test for readability after editing. Apply the smallest evidence-supported batch, explain why each change corrects the test rather than hides a product defect, and rerun only the affected test. Continue analyzing, editing, and rerunning until the final representative evidence supports readiness or a genuine blocker remains. Do not stop based on a fixed rerun count. Stop when the evidence indicates an application regression, an environment or product dependency prevents progress, or no evidence-supported test, context, data, or configuration improvement remains; report the original and final evidence, changes attempted, and recommended owner/action.