@loadmill/droid-cua 2.25.0 → 2.27.0

package/README.md

@@ -48,7 +48,10 @@ Open the desktop app and choose the platform you want to test.
 
 **3. Choose your AI provider**
 
-In Settings, choose the CUA model you want to run. `Loadmill - Smart` uses your Loadmill sign-in and usage tracking. The OpenAI models use your own OpenAI API key.
+In Settings, choose the CUA model you want to run. Loadmill Smart is the
+recommended option, Pulse is fast and efficient, and Beacon is experimental.
+The Loadmill models use your Loadmill sign-in and usage tracking. The OpenAI
+models use your own OpenAI API key.
 
 **4. Connect a target device**
 
@@ -75,7 +78,7 @@ Desktop app support:
 ## Requirements
 
 **All platforms:**
-- Loadmill sign-in for `Loadmill - Smart`, or an OpenAI API key for the OpenAI models
+- Loadmill sign-in for the Loadmill models, or an OpenAI API key for the OpenAI models
 
 **Android:**
 - Android Debug Bridge (ADB)
@@ -247,6 +250,7 @@ Supported CLI options include:
 - `--no-context`
 - `--context-optimization-threshold`
 - `--no-context-optimization`
+- `--explain`
 - `--base-prompt`
 - `--execution-prompt`
 - `--base-prompt-file`
@@ -254,11 +258,12 @@ Supported CLI options include:
 - `--secrets`
 - `--record`
 - `--report`
+- `--no-cloud-report`
 - `--debug`
 
-`--cua-model` accepts `loadmill-smart`, `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`.
+`--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`.
 
 Config and precedence rules:
 - Use `--config <file>` to supply prompt-affecting settings for headless runs.
@@ -268,6 +273,8 @@ Config and precedence rules:
 - Context Optimization is enabled by default with a `30000` input-token threshold.
 - `--context-optimization-threshold <tokens>` sets the threshold and enables Context Optimization.
 - `--no-context-optimization` disables Context Optimization.
+- `--explain` enables Explain Mode for the run. Explain Mode asks the agent for concise explanations of non-obvious decisions, skipped actions, and completion evidence; explanations appear in terminal output and reports.
+- Set `"explainMode": true` in the JSON config to enable the same behavior without a flag. Explain Mode is off by default, and `--explain` enables it when the config leaves it off.
 - `--base-prompt` and `--execution-prompt` let you pass prompt customizations inline on the command line.
 - `--base-prompt-file` and `--execution-prompt-file` override the corresponding prompt customizations from config.
 - If both inline and file-based prompt overrides are provided, the inline prompt flags win.
@@ -283,6 +290,7 @@ HTML report (`--report`):
 - Writes a self-contained HTML report of the run — the same Run Details view the desktop app shows, with screenshots inlined — that you can share and open in any browser.
 - With no value it saves `<test>--<date>--<time>.html` (e.g. `login--2026-06-03--16-09-20.html`) in the current directory; pass `--report <file>` to pick a filename or `--report <dir>` to pick a folder.
 - In the desktop app the same report is available from a run's **Share → Download HTML report** button.
+- Authenticated headless runs upload their HTML report and screenshots to Loadmill by default. Use `--no-cloud-report` to disable that artifact upload. The basic Droid run row is still reported to Loadmill.
 
 ```sh
 droid-cua --avd adb:emulator-5554 --instructions tests/login.dcua --report ./reports

package/build/index.js

@@ -1,3 +1,4 @@
+const processStartTime = Date.now();
 import minimist from "minimist";
 import dotenv from "dotenv";
 import path from "path";
@@ -17,7 +18,7 @@ import { resolveExecutionTestData } from "./src/core/test-data.js";
 import { getDefaultSecretsPath, resolveExecutionSecrets } from "./src/core/secrets.js";
 import { assertRuntimeCredentialsForProvider, createRunContext, resolveRuntimeConfigFromEnv, resolveRuntimeCredentialsFromEnv, } from "./src/core/runtime-config.js";
 import { resolveHeadlessExecutionConfig } from "./src/cli/headless-execution-config.js";
-import { resolveHeadlessTarget } from "./src/cli/headless-target.js";
+import { resolveHeadlessTarget, shouldWaitForLoadmillCloudCompletion } from "./src/cli/headless-target.js";
 import { createHeadlessDebugArtifacts } from "./src/cli/headless-debug.js";
 import { loadHeadlessInstructions } from "./src/cli/headless-instructions.js";
 import { listHeadlessInstructionFiles, resolveHeadlessInstructionsTarget } from "./src/cli/headless-instruction-target.js";
@@ -25,12 +26,33 @@ import { runHeadlessInstructionRuns } from "./src/cli/headless-runner.js";
 import { planScenarioRuns } from "./src/cli/scenario-planner.js";
 import { resolveLambdaTestCredentials, uploadLambdaTestCliApp } from "./src/cli/lambdatest-app-upload.js";
 import { resolveAwsDeviceFarmCredentials, uploadAwsDeviceFarmCliApp } from "./src/cli/aws-device-farm-app-upload.js";
+import { resolveLoadmillCloudCredentials } from "./src/cli/loadmill-cloud-credentials.js";
+import { formatCloudUsageReport } from "./src/cli/loadmill-cloud-usage.js";
+import { LoadmillCloudControlPlaneClient } from "./src/device/cloud/loadmill-cloud/control-plane-client.js";
 import { createStatusLine } from "./src/cli/cloud-status-line.js";
 import { createLoadmillApiClient } from "./src/integrations/loadmill/client.js";
+import { droidReportUploadManager } from "./src/integrations/loadmill/report-upload-manager.js";
 import { getCloudProviderAdapter } from "./src/device/cloud/registry.js";
 import { setCloudProgressListener } from "./src/device/cloud/progress.js";
 import { runSkillCommand } from "./src/cli/skill-command.js";
+import { isLoadmillCloudUsageLimitError } from "./src/device/cloud/loadmill-cloud/errors.js";
+import { loadmillCloudAdapter } from "./src/device/cloud/loadmill-cloud/adapter.js";
+import { formatDuration } from "./src/core/report/run-log-model.js";
 dotenv.config();
+process.once("SIGTERM", async () => {
+    process.exitCode = 143;
+    // Registering a SIGTERM listener cancels Node's default terminate, so exit
+    // explicitly; await the /stop because a bare fire-and-forget fetch may not
+    // dispatch before exit. Capped so a slow server can't hang the exit.
+    await Promise.race([
+        loadmillCloudAdapter.releaseActiveSession(),
+        new Promise((resolve) => setTimeout(resolve, 1_500)),
+    ]);
+    process.exit(143);
+});
+process.once("beforeExit", () => {
+    loadmillCloudAdapter.releaseActiveSession();
+});
 const args = minimist(process.argv.slice(2));
 if (args._[0] === "skill") {
     try {
@@ -57,6 +79,7 @@ const debugMode = args["debug"] || false;
 const reportConfig = {
     enabled: args.report === true || (typeof args.report === "string" && args.report.trim().length > 0),
     path: typeof args.report === "string" && args.report.trim().length > 0 ? args.report.trim() : null,
+    cloudEnabled: args["no-cloud-report"] !== true,
 };
 const screenshotDir = path.join("droid-cua-recording-" + Date.now());
 if (recordScreenshots)
@@ -173,6 +196,84 @@ async function resolveLambdaTestDashboardUrl(credentials, sessionId, { attempts
     return null;
 }
 async function main() {
+    if (args["cloud-usage"] != null) {
+        try {
+            const credentials = resolveLoadmillCloudCredentials(process.env);
+            const client = new LoadmillCloudControlPlaneClient({
+                bearerToken: credentials.bearerToken,
+                baseUrl: credentials.baseUrl,
+            });
+            const usage = await client.getUsage();
+            for (const line of formatCloudUsageReport(usage)) {
+                console.log(line);
+            }
+            process.exit(0);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const code = error?.code ? ` [${error.code}]` : "";
+            console.error(`Failed to fetch Loadmill Cloud usage: ${message}${code}`);
+            process.exit(1);
+        }
+    }
+    // Pure retroactive artifact fetch: `--cloud-session-id <sid> --artifacts <kinds>`
+    // with no --instructions. Reattaching to a terminal run and downloading its
+    // recordings/logs doesn't require driving anything, so it doesn't need the
+    // full headless-instructions machinery below (which requires --instructions
+    // for every cloud device-source run).
+    if (targetConfig.deviceSource === "loadmill-cloud" &&
+        targetConfig.cloudSessionId &&
+        Array.isArray(targetConfig.artifacts) &&
+        targetConfig.artifacts.length > 0 &&
+        !instructionsFile) {
+        const credentials = resolveLoadmillCloudCredentials(process.env);
+        // Share the exact same rendering the normal run command uses — install
+        // the progress listener before touching the adapter, since prepareSession
+        // reports poll/download progress unconditionally and would otherwise be
+        // silently dropped (no listener installed => no output for 10-20s).
+        const retroactiveStatusLine = createStatusLine();
+        setCloudProgressListener((event) => {
+            // The run may still be finishing up on the cloud device when this
+            // starts — only switch the umbrella label to "fetching" once the
+            // artifact list is actually in hand and downloads are starting.
+            if (event.kind === "note" && event.message === "Fetching artifacts") {
+                retroactiveStatusLine.rename("Fetching Loadmill Cloud artifacts");
+            }
+            retroactiveStatusLine.handleEvent(event);
+        });
+        try {
+            retroactiveStatusLine.start("Waiting for Loadmill Cloud artifacts");
+            await connectToDevice({
+                source: "loadmill-cloud",
+                providerId: "loadmill-cloud",
+                platform: targetConfig.platform,
+                deviceName: targetConfig.deviceName,
+                osVersion: targetConfig.osVersion,
+                appRef: targetConfig.appPath,
+                credentials,
+                cloudSessionId: targetConfig.cloudSessionId,
+                artifacts: targetConfig.artifacts,
+            }, null, { log: () => { } });
+            retroactiveStatusLine.stop();
+            // A resumable (non-terminal) session reconnected successfully instead of
+            // exiting via the terminal/artifacts branch above — there's nothing to
+            // drive without --instructions, so release the slot and say so.
+            await loadmillCloudAdapter.releaseSession(credentials, { waitForCompletion: false });
+            console.error(`Loadmill Cloud session ${targetConfig.cloudSessionId} is not terminal yet; add --instructions to drive it, or wait until it finishes and re-run this same command to fetch artifacts.`);
+            process.exit(1);
+        }
+        catch (error) {
+            retroactiveStatusLine.stop();
+            if (error?.artifactsOnlyExit) {
+                console.log(error.message);
+                console.log(`Done in ${formatDuration(Date.now() - processStartTime)}.`);
+                process.exit(0);
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`Loadmill Cloud artifact fetch failed: ${message}`);
+            process.exit(1);
+        }
+    }
     if (targetConfig.listDevices) {
         const credentials = resolveAwsDeviceFarmCredentials(process.env);
         const adapter = getCloudProviderAdapter("aws-device-farm");
@@ -188,12 +289,15 @@ async function main() {
     const isBrowserTarget = targetConfig.target === "web";
     const isLambdaTestTarget = targetConfig.deviceSource === "lambdatest";
     const isAwsDeviceFarmTarget = targetConfig.deviceSource === "aws-device-farm";
-    const isCloudTarget = isLambdaTestTarget || isAwsDeviceFarmTarget;
+    const isLoadmillCloudTarget = targetConfig.deviceSource === "loadmill-cloud";
+    const isCloudTarget = isLambdaTestTarget || isAwsDeviceFarmTarget || isLoadmillCloudTarget;
     let lambdaTestSessionConnected = false;
     let lambdaTestSessionUrl = null;
     let lambdaTestCredentials = null;
     let awsSessionConnected = false;
     let awsDeviceFarmStatusLine = null;
+    let loadmillCloudSessionConnected = false;
+    let loadmillCloudStatusLine = null;
     const headlessDebug = createHeadlessDebugArtifacts({
         cwd: process.cwd(),
         enabled: isHeadlessInstructionsRun && debugMode
@@ -407,6 +511,94 @@ async function main() {
         console.log(`Using real resolution: ${deviceInfo.device_width}x${deviceInfo.device_height}`);
         console.log(`Model sees resolution: ${deviceInfo.scaled_width}x${deviceInfo.scaled_height}`);
     }
+    else if (isLoadmillCloudTarget) {
+        const loadmillCloudCredentials = resolveLoadmillCloudCredentials(process.env);
+        loadmillCloudStatusLine = createStatusLine();
+        const statusLine = loadmillCloudStatusLine;
+        setCloudProgressListener((event) => statusLine.handleEvent(event));
+        const provisioningAbortController = new AbortController();
+        let loadmillCloudSigintHandled = false;
+        let loadmillCloudInterruptRequested = false;
+        process.once("SIGINT", async () => {
+            if (loadmillCloudSigintHandled)
+                return;
+            loadmillCloudSigintHandled = true;
+            loadmillCloudInterruptRequested = true;
+            console.log("\nStopping Loadmill Cloud session...");
+            provisioningAbortController.abort(new Error("Stopped by user"));
+            if (!loadmillCloudSessionConnected) {
+                process.exitCode = 130;
+                return;
+            }
+            await disconnectDevice({ waitForCompletion: false });
+            loadmillCloudAdapter.releaseActiveSession();
+            process.exit(130);
+        });
+        try {
+            statusLine.start("Starting Loadmill Cloud session");
+            targetId = await connectToDevice({
+                source: "loadmill-cloud",
+                providerId: "loadmill-cloud",
+                platform: targetConfig.platform,
+                deviceName: targetConfig.deviceName,
+                osVersion: targetConfig.osVersion,
+                appRef: targetConfig.appPath,
+                credentials: loadmillCloudCredentials,
+                sessionName: `droid-cua-cli-${new Date().toISOString()}`,
+                cloudSessionId: targetConfig.cloudSessionId,
+                artifacts: targetConfig.artifacts,
+                signal: provisioningAbortController.signal,
+            }, null, 
+            // These are one-off descriptive messages (not the name of the
+            // in-progress step), so they must render as persistent ℹ lines —
+            // never painted into the volatile detail slot, where a stray message
+            // like "Connected to ..." would linger after its moment has passed
+            // and contradict an already-closed "✔ <phase>" line above it.
+            { log: (message) => statusLine.handleEvent({ kind: "note", message }) });
+            loadmillCloudSessionConnected = true;
+            if (loadmillCloudInterruptRequested) {
+                try {
+                    await disconnectDevice({ waitForCompletion: false });
+                    loadmillCloudAdapter.releaseActiveSession();
+                }
+                finally {
+                    statusLine.stop();
+                    loadmillCloudSessionConnected = false;
+                    process.exitCode = 130;
+                }
+                return;
+            }
+            deviceInfo = await getDeviceInfo(targetId);
+            statusLine.stop();
+        }
+        catch (error) {
+            statusLine.stop();
+            if (error?.artifactsOnlyExit) {
+                console.log(error.message);
+                process.exitCode = 0;
+                return;
+            }
+            if (loadmillCloudSessionConnected) {
+                await disconnectDevice({ waitForCompletion: false });
+                loadmillCloudAdapter.releaseActiveSession();
+                loadmillCloudSessionConnected = false;
+            }
+            if (loadmillCloudInterruptRequested) {
+                process.exitCode = 130;
+                return;
+            }
+            if (isLoadmillCloudUsageLimitError(error)) {
+                const suffix = error.code ? ` (${error.code})` : "";
+                console.error(`\n${error.message}${suffix}`);
+                process.exitCode = 1;
+                return;
+            }
+            throw error;
+        }
+        console.log(`Connected to Loadmill Cloud device "${targetConfig.deviceName}" (${targetId})`);
+        console.log(`Using real resolution: ${deviceInfo.device_width}x${deviceInfo.device_height}`);
+        console.log(`Model sees resolution: ${deviceInfo.scaled_width}x${deviceInfo.scaled_height}`);
+    }
     else {
         targetId = await connectToDevice(avdName, platform);
         deviceInfo = await getDeviceInfo(targetId);
@@ -420,6 +612,7 @@ async function main() {
     // If --instructions provided, run in headless mode
     if (instructionsFile) {
         let exitCode = null;
+        let succeeded = false;
         try {
             const headlessConfig = preloadedHeadlessConfig;
             const appContext = preloadedAppContext;
@@ -427,6 +620,7 @@ async function main() {
             const runtimeContext = createCliRuntimeContext({
                 llmProviderMode: headlessConfig.llmProviderMode,
                 cuaModel: headlessConfig.cuaModel,
+                explainMode: headlessConfig.explainMode,
                 promptCustomizations: headlessConfig.promptCustomizations,
                 contextOptimizationEnabled: headlessConfig.contextOptimizationEnabled,
                 contextOptimizationThreshold: headlessConfig.contextOptimizationThreshold,
@@ -477,8 +671,10 @@ async function main() {
                 report: reportConfig
             });
             exitCode = result.exitCode;
+            succeeded = true;
         }
         finally {
+            await droidReportUploadManager.drain();
             if (lambdaTestSessionConnected) {
                 console.log("Ending LambdaTest session...");
                 await disconnectDevice();
@@ -505,6 +701,18 @@ async function main() {
                 awsSessionConnected = false;
                 console.log("AWS Device Farm session ended.");
             }
+            if (loadmillCloudSessionConnected) {
+                console.log("Ending Loadmill Cloud session...");
+                loadmillCloudStatusLine.start("Ending Loadmill Cloud session");
+                await disconnectDevice({ waitForCompletion: shouldWaitForLoadmillCloudCompletion(targetConfig) });
+                loadmillCloudAdapter.releaseActiveSession();
+                loadmillCloudStatusLine.stop();
+                loadmillCloudSessionConnected = false;
+                console.log("Loadmill Cloud session ended.");
+                if (succeeded) {
+                    console.log(`Done in ${formatDuration(Date.now() - processStartTime)}.`);
+                }
+            }
         }
         if (exitCode !== null) {
             process.exit(exitCode);

package/build/src/cli/cloud-status-line.js

@@ -1,14 +1,5 @@
 const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
-/**
- * Heroku-style volatile status line for long-running cloud-provider steps.
- * On a TTY each progress update overwrites the previous one (spinner + step
- * name + elapsed + latest detail) and the whole line is cleared when the step
- * finishes. On a non-TTY (CI, piped output) it degrades to plain log lines,
- * printed only when the detail changes. Feed it cloud progress events via
- * handleEvent: "phase" events time named sub-steps and "note" events keep
- * persistent info; both are printed (prefixed with `indent`) when the step
- * finishes.
- */
+const HEARTBEAT_INTERVAL_MS = 10_000;
 export function createStatusLine({ stream = process.stderr, indent = "" } = {}) {
     const tty = stream.isTTY;
     let active = false;
@@ -18,7 +9,6 @@ export function createStatusLine({ stream = process.stderr, indent = "" } = {})
     let detail = "";
     let startedAt = 0;
     let lastPrintedDetail = "";
-    let entries = [];
     let currentPhase = null;
     const render = () => {
         frame = (frame + 1) % SPINNER_FRAMES.length;
@@ -26,19 +16,45 @@ export function createStatusLine({ stream = process.stderr, indent = "" } = {})
         const line = `${SPINNER_FRAMES[frame]} ${stepName} (${seconds}s)${detail ? ` — ${detail}` : ""}`;
         stream.write(`\r\x1b[2K${line}`);
     };
+    const heartbeat = () => {
+        const seconds = Math.floor((Date.now() - startedAt) / 1000);
+        console.log(`… ${stepName}: still waiting (${seconds}s)${detail ? ` — ${detail}` : ""}`);
+    };
+    const printPersistent = (text) => {
+        if (tty) {
+            stream.write(`\r\x1b[2K${text}\n`);
+        }
+        else {
+            console.log(text);
+        }
+    };
     const closePhase = () => {
         if (currentPhase) {
-            currentPhase.ms = Date.now() - currentPhase.startedAt;
+            if (currentPhase.closeText != null) {
+                printPersistent(`${indent}\x1b[32m✔\x1b[0m ${currentPhase.closeText}`);
+            }
+            else {
+                const ms = Date.now() - currentPhase.startedAt;
+                printPersistent(`${indent}\x1b[32m✔\x1b[0m ${currentPhase.name} \x1b[90m(${ms}ms)\x1b[0m`);
+            }
             currentPhase = null;
         }
     };
     return {
+        rename(name) {
+            if (!active) {
+                return;
+            }
+            stepName = name;
+            if (tty) {
+                render();
+            }
+        },
         start(name) {
             active = true;
             stepName = name;
             detail = "";
             lastPrintedDetail = "";
-            entries = [];
             currentPhase = null;
             startedAt = Date.now();
             if (tty) {
@@ -46,6 +62,12 @@ export function createStatusLine({ stream = process.stderr, indent = "" } = {})
                 // on its own row before this step starts drawing.
                 timer = setInterval(render, 120);
             }
+            else {
+                timer = setInterval(heartbeat, HEARTBEAT_INTERVAL_MS);
+                if (typeof timer.unref === "function") {
+                    timer.unref();
+                }
+            }
         },
         update(message) {
             if (!active) {
@@ -66,11 +88,30 @@ export function createStatusLine({ stream = process.stderr, indent = "" } = {})
             }
             if (event.kind === "phase") {
                 closePhase();
-                currentPhase = { kind: "phase", name: event.message, startedAt: Date.now(), ms: 0 };
-                entries.push(currentPhase);
+                currentPhase = { name: event.message, startedAt: Date.now(), closeText: null };
             }
             else if (event.kind === "note") {
-                entries.push({ kind: "note", text: event.message });
+                printPersistent(`${indent}\x1b[34mℹ\x1b[0m ${event.message}`);
+                return;
+            }
+            else if (event.kind === "phase-close-text") {
+                if (currentPhase) {
+                    currentPhase.closeText = event.message;
+                }
+                return;
+            }
+            else if (event.kind === "phase-flush") {
+                closePhase();
+                return;
+            }
+            else if (event.kind === "print") {
+                // Closes any still-open phase first (flushing its "✔ ..." line)
+                // before printing the caller-supplied text verbatim, so a final
+                // summary can never race ahead of / glue onto the last phase's
+                // close line or the live spinner.
+                closePhase();
+                printPersistent(event.message);
+                return;
             }
             this.update(event.message);
         },
@@ -80,19 +121,10 @@ export function createStatusLine({ stream = process.stderr, indent = "" } = {})
                 clearInterval(timer);
                 timer = null;
             }
+            closePhase();
             if (tty) {
                 stream.write("\r\x1b[2K");
             }
-            closePhase();
-            for (const entry of entries) {
-                if (entry.kind === "phase") {
-                    stream.write(`${indent}\x1b[32m✔\x1b[0m ${entry.name} \x1b[90m(${entry.ms}ms)\x1b[0m\n`);
-                }
-                else {
-                    stream.write(`${indent}\x1b[34mℹ\x1b[0m ${entry.text}\n`);
-                }
-            }
-            entries = [];
         }
     };
 }

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

@@ -129,6 +129,7 @@ async function loadConfigFromFile(configPath) {
         llmProviderMode: undefined,
         cuaModel: undefined,
         aimAssistMode: undefined,
+        explainMode: undefined,
         promptCustomizations: createEmptyPromptCustomizations(),
         appContextEnabled: undefined,
         appContextPath: undefined,
@@ -144,6 +145,12 @@ async function loadConfigFromFile(configPath) {
     if ("aimAssistMode" in rawConfig) {
         normalized.aimAssistMode = validateAimAssistMode(rawConfig.aimAssistMode, "config.aimAssistMode");
     }
+    if ("explainMode" in rawConfig) {
+        if (typeof rawConfig.explainMode !== "boolean") {
+            throw new Error("config.explainMode must be a boolean.");
+        }
+        normalized.explainMode = rawConfig.explainMode;
+    }
     if ("promptCustomizations" in rawConfig) {
         normalized.promptCustomizations = normalizePromptCustomizations(rawConfig.promptCustomizations, "config.promptCustomizations");
     }
@@ -217,6 +224,7 @@ export async function resolveHeadlessExecutionConfig(args, options = {}) {
         llmProviderMode: fileConfig?.llmProviderMode || readEnvDefaultLlmProviderMode(),
         cuaModel: fileConfig?.cuaModel || readEnvDefaultCuaModel(),
         aimAssistMode: fileConfig?.aimAssistMode || DEFAULT_AIM_ASSIST_MODE,
+        explainMode: fileConfig?.explainMode ?? false,
         promptCustomizations,
         appContextEnabled: fileConfig?.appContextEnabled ?? true,
         appContextPath: fileConfig?.appContextPath || null,
@@ -235,6 +243,9 @@ export async function resolveHeadlessExecutionConfig(args, options = {}) {
     if (typeof args["aim-assist"] === "string") {
         resolved.aimAssistMode = validateAimAssistMode(args["aim-assist"], "--aim-assist");
     }
+    if (args.explain === true) {
+        resolved.explainMode = true;
+    }
     if (hasContextOptimizationThresholdFlag) {
         resolved.contextOptimizationEnabled = true;
         resolved.contextOptimizationThreshold = parseContextOptimizationThreshold(args["context-optimization-threshold"], "--context-optimization-threshold");