@loadmill/droid-cua 2.23.0 → 2.25.0

package/build/src/prompts/execution.js

@@ -1,4 +1,5 @@
 import { DEFAULT_AIM_ASSIST_MODE } from "../core/aim-assist.js";
+import { CUA_CONVERSATION_POLICIES, resolveConversationPolicy } from "../core/cua-models.js";
 import { normalizeSecretKeys } from "../core/secrets.js";
 import { appendCustomSections, buildBaseSystemPrompt, isBrowserTarget } from "./base.js";
 export function buildAppContextSection(text) {
@@ -43,10 +44,14 @@ export function buildExecutionModePrompt(deviceInfo, customInstructions = {}, ap
     const testDataContextSection = buildTestDataContextSection(options.testDataContext);
     const secretKeysContextSection = buildSecretKeysContextSection(options.availableSecretKeys);
     const browserTarget = isBrowserTarget(deviceInfo);
+    const conversationPolicy = resolveConversationPolicy(options.cuaModel);
+    const instructionContextRule = conversationPolicy === CUA_CONVERSATION_POLICIES.ISOLATED
+        ? "This model starts each instruction without prior model history. Execute only the current instruction and stop when it is complete."
+        : "Instructions are sequential parts of one scenario. Use prior instructions and outcomes to resolve references in the current instruction, but execute only the current instruction. Preserve expected values established earlier; never replace them with the observed state merely to produce a pass.";
     const prompt = `${basePrompt}
 
 EXECUTION MODE - Critical Behavior:
-You are executing test script commands one at a time. This is NOT a conversation.
+You are executing test script commands one at a time. This is an automated test run, not a chat with the user.
 
 CRITICAL RULES:
 - DO NOT generate conversational text or narration
@@ -70,14 +75,20 @@ Your process:
    - Before calling \`assert\`, make sure the current screen contains the evidence needed to validate the condition. If needed, perform only minimal preparation first, such as taking a screenshot, waiting briefly, closing the keyboard, scrolling within the relevant view, or opening the relevant menu.
    - Once you call \`assert\`, validation is read-only. The assertion tool will not click, type, wait, scroll, request screenshots, or change the device state.
    - Use \`navigate\` for direct browser navigation instead of trying to manipulate the address bar
+${browserTarget ? "" : `   - Every \`type\` action must end its computer-action batch so you can inspect the post-type screenshot
+   - Call \`close_keyboard\` next when a full software keyboard is visible, or after typing into an iOS secure field even when its keyboard is hidden
+   - Do not complete the current instruction while that required \`close_keyboard\` action is pending
+   - Otherwise, including when only a slim hardware-keyboard toolbar or suggestions are visible, continue without \`close_keyboard\`
+   - Apply the same dismissal decision after \`type_sensitive_text\`
+`}
    - Use the \`loadmill\` tool whenever the instruction explicitly references running or using a Loadmill flow. Pass the requested flow name/intent and parameters as the command; the tool will search Loadmill, select the best matching flow, run it, and wait for completion. Do not handle Loadmill by typing in the app UI.
 3. Execute the required actions
-4. Before tapping a mutating action, dismiss the keyboard if it is open and not needed
+4. ${browserTarget ? "Before tapping a mutating action, dismiss the keyboard if it is open and not needed" : "Use `close_keyboard` before any later interaction when the post-type dismissal rules require it"}
 5. After a mutating action, inspect the resulting screen for success cues such as cleared fields, reset buttons, changed status, refreshed content, or navigation
 6. Stop as soon as success is visible
 7. Stop immediately - no commentary, no questions
 
-Each instruction is independent. Do not reference previous instructions or ask about next steps.
+${instructionContextRule}
 ${appContextSection ? `\n\n${appContextSection}` : ""}${testDataContextSection ? `\n\n${testDataContextSection}` : ""}${secretKeysContextSection ? `\n\n${secretKeysContextSection}` : ""}`;
     return appendCustomSections(prompt, [
         { title: "Base Prompt Instructions", text: customInstructions.basePromptInstructions },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loadmill/droid-cua",
-  "version": "2.23.0",
+  "version": "2.25.0",
   "description": "AI-powered Android testing agent using OpenAI's computer-use model and ADB",
   "main": "build/index.js",
   "type": "module",
@@ -10,6 +10,7 @@
   "files": [
     "build/**/*",
     "bin/**/*",
+    "skill/**/*",
     "README.md",
     "LICENSE"
   ],

package/skill/droid-cua/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: droid-cua
+description: Operate Droid CUA `.dcua` test projects. Use when the user explicitly names Droid CUA or @loadmill/droid-cua, or asks to author, configure, run, or diagnose `.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.
+---
+
+# Droid CUA
+
+Use the existing `droid-cua` CLI and repository files. Do not invent commands, flags, or product capabilities.
+
+## Workflow
+
+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.
+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. Report the outcome, evidence paths, changes made, and whether the failure belongs to the test, environment, or product.
+
+## Safety
+
+- Never print, open, or echo secret values. Check only whether required keys are configured.
+- Never search for credentials outside the active test project or source another project's `.env` file.
+- Use Loadmill for every run unless the user explicitly asks to use their own OpenAI API key. A discovered OpenAI key is never permission to switch providers.
+- Never use credentials from another project, a skill, an agent configuration, or the user's home directory. Configure credentials only in the active test project's `.env` (or an explicitly supplied CI secret).
+- 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.
+- Make one minimal change and run the affected test again. Stop after two edit/rerun cycles and present the evidence.
+- Stop immediately when evidence indicates a likely application regression; do not rewrite the test to match broken behavior.
+- Gracefully allow cloud runs to finish cleanup. Avoid terminating a metered device session unless necessary.
+
+## Operating principles
+
+- 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.
+- 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.

package/skill/droid-cua/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Droid Cua"
+  short_description: "Operate Droid CUA .dcua test projects"
+  icon_small: "./assets/droid-cua-app-icon.png"
+  icon_large: "./assets/droid-cua-app-icon.png"
+  brand_color: "#1895F7"

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

@@ -0,0 +1,39 @@
+# Authoring tests
+
+## Inspect first
+
+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`.
+
+## Write `.dcua` instructions
+
+- Put one clear instruction or assertion on each non-empty line.
+- Describe visible UI intent, not coordinates, selectors, implementation details, or model strategy.
+- Prefer a high-level business intent when `context.md` makes the flow unambiguous. Do not translate every tap and keystroke into a brittle micro-script.
+- Break an instruction down only when the agent demonstrably needs help finding a control or completing part of the flow.
+- 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.
+- Keep each test focused on one behavior. Split unrelated flows.
+- Use `//` comments sparingly for human context; comments are not executed.
+- Never include secret values in the test.
+
+Example:
+
+```text
+Sign in using the USER_EMAIL and USER_PASSWORD secrets.
+Assert that the Home screen is visible and shows the signed-in account.
+```
+
+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.
+
+## Put knowledge in the right place
+
+- Put durable product behavior and terminology in `context.md`, not repeated in every test.
+- Put non-secret reusable people, accounts, products, and scenario combinations in `test-data.md`.
+- Put credentials and sensitive values in `.secrets`.
+- Put reproducible headless settings in `ci/droid-cua.json`.
+- Keep environment and provider credentials in `.env` or the shell/CI secret store.
+
+Use `--scenario "<goal>" --test-data <path>` only when the user wants generated permutations or cases. A normal `.dcua` run does not automatically consume `test-data.md`.
+
+After editing, show the user the test instructions and explain any new context, data keys, or secret keys required. Never show secret values.

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

@@ -0,0 +1,74 @@
+# Onboarding and troubleshooting
+
+Follow the Desktop Device Setup Wizard sequence: choose a platform, run checks, discover/connect a target, verify runtime access during the requested run, then continue the original task. Run authentication as the separate first preflight described in `project-and-auth.md`.
+
+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.
+
+## Android
+
+Resolve `adb` and `emulator` from `ANDROID_HOME`, `ANDROID_SDK_ROOT`, the macOS default `~/Library/Android/sdk`, the Windows default `%LOCALAPPDATA%\Android\Sdk`, then `PATH`. Respect explicit `DROID_CUA_ANDROID_ADB_PATH` and `DROID_CUA_ANDROID_EMULATOR_PATH` overrides.
+
+Run these checks:
+
+```sh
+adb version
+emulator -list-avds
+adb devices
+```
+
+- `adb` is blocking.
+- The emulator CLI and existence of an AVD are individually non-blocking.
+- Target availability is blocking and passes when `adb devices` contains a `device` entry or `emulator -list-avds` contains a launchable AVD.
+- For `unauthorized`, ask the user to accept the computer authorization prompt on the device.
+- For `offline`, reconnect the device or restart ADB, then retry.
+- If nothing is available, guide the user to connect a device or create an AVD in Android Studio Device Manager.
+
+Use `--avd adb:<serial>` for an attached target and `--avd avd:<name>` to launch an AVD.
+
+## iOS
+
+Local iOS execution requires macOS. Run checks in this order:
+
+```sh
+xcrun --version
+xcode-select -p
+xcodebuild -license check
+xcodebuild -checkFirstLaunchStatus
+node --version
+npm --version
+appium --version
+appium driver list --installed
+xcrun simctl list devices --json
+```
+
+Require `xcode-select -p` to point to an `/Xcode*.app/Contents/Developer` path, an installed XCUITest driver, and at least one available iPhone simulator. A booted simulator is helpful but not blocking.
+
+Offer only the relevant remediation, with approval:
+
+```sh
+sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
+sudo xcodebuild -license accept
+sudo xcodebuild -runFirstLaunch
+npm install -g appium
+appium driver install xcuitest
+```
+
+Use `--platform ios --avd "<simulator name>"` for the run.
+
+## Web
+
+Droid CUA automatically discovers Chrome or Edge on macOS and Windows. Check the standard application locations, then run the requested test with `--target web --browser <chrome|edge> --session-mode fresh`. A successful Playwright launch is the runtime verification; do not create a persistent setup-only test.
+
+On Linux, automatic installed-browser discovery is not currently supported. Do not claim that a PATH-installed browser will be found.
+
+## Cloud targets
+
+For LambdaTest, require `LAMBDATEST_USERNAME`, `LAMBDATEST_ACCESS_KEY`, a device name, OS version, and `.apk` or `.ipa`. The CLI uploads the app for each run.
+
+For AWS Device Farm, require `AWS_DEVICE_FARM_ACCESS_KEY_ID`, `AWS_DEVICE_FARM_SECRET_ACCESS_KEY`, and `AWS_DEVICE_FARM_PROJECT_ARN`. Discover targets with:
+
+```sh
+droid-cua --device-source aws-device-farm --list-devices
+```
+
+Do not document BrowserStack CLI runs; BrowserStack is not consistently exposed by the current CLI.

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

@@ -0,0 +1,41 @@
+# Project files and authentication
+
+## Project files
+
+- `.dcua`: executable test instructions. Each non-empty line is one instruction; `//` begins a comment.
+- `context.md`: durable knowledge about product terminology, screens, navigation, and behavior. Pass it with `--context`, or reference it from `ci/droid-cua.json`.
+- `test-data.md`: non-secret entities and scenario inputs. It is used with `--scenario` and `--test-data`; it is not automatically loaded by every normal test run.
+- `.secrets`: dotenv-style values that Droid CUA may type into the tested application. The model receives the keys, not the resolved values. Headless execution loads this file from the current working directory; `--secrets` overrides it.
+- `.env`: infrastructure credentials and runtime environment variables loaded from the current working directory, including `LOADMILL_API_TOKEN`.
+- `ci/droid-cua.json`: optional checked-in headless config. Paths inside it are relative to the config file.
+- `logs/`: structured JSONL and screenshot artifacts created by `--debug`.
+- HTML reports: self-contained evidence produced by `--report`.
+
+Keep `.env` and `.secrets` out of version control. Use `git check-ignore -q .env` and `git check-ignore -q .secrets` to check ignore coverage without opening either file.
+
+## Loadmill authentication
+
+Loadmill is the required default LLM provider. Use it unless the user explicitly asks to use their own OpenAI API key. Never switch to OpenAI because a Loadmill token is missing or because an OpenAI key happens to be available.
+
+Before a run, check only for the presence of a Loadmill token in the active test project's `.env` or explicitly supplied CI secret:
+
+```sh
+grep -Eq '^LOADMILL_API_TOKEN=.+$' .env 2>/dev/null
+```
+
+Run this check from the active test project's working directory. Do not print the variable, run `env`, open `.env`, or inspect inherited environment variables. Do not search parent directories, sibling repositories, the user's home directory, agent skills/configuration, or the Droid CUA source repository for credentials.
+
+If it is missing, explain that Droid CUA uses a Loadmill token by default and guide the user to:
+
+1. Sign in, then open [Loadmill Settings → Security](https://app.loadmill.com/app/user/settings/security).
+2. Create an API token with a description such as `Droid CUA CLI`.
+3. Copy it when shown; Loadmill shows it once.
+
+Offer exactly these two choices, then wait for the user's selection:
+
+1. **Use it once:** The user provides the token through the agent's secret-input mechanism and asks to use it for this run only. Pass it only to that command through a secret-safe mechanism; do not write it to `.env`, a shell profile, or any other file.
+2. **Save it for this project:** The user provides the token through the agent's secret-input mechanism and approves saving it. Create the active project's `.env` if needed or add/update only its `LOADMILL_API_TOKEN` entry. First ensure `.env` is ignored by version control; add `.env` to the active project's `.gitignore` when needed.
+
+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.

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

@@ -0,0 +1,110 @@
+# Running, monitoring, and guarded healing
+
+## Construct the run
+
+Prefer a single test before a directory or scenario run. Preserve an existing provider/model choice in `ci/droid-cua.json`; otherwise use the Loadmill provider. Use Loadmill Smart as the recommended default, or Loadmill Beacon when the user prioritizes faster, lower-cost execution:
+
+```sh
+# Recommended default
+--llm-provider loadmill --cua-model loadmill-smart
+
+# Faster, lower-cost option
+--llm-provider loadmill --cua-model loadmill-beacon
+```
+
+Both Loadmill models require `LOADMILL_API_TOKEN`. Do not switch between Smart and Beacon silently; preserve the project's model or explain the speed/cost tradeoff 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.
+
+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.
+
+```sh
+# Attached Android device or running emulator
+droid-cua --llm-provider loadmill --cua-model loadmill-smart --avd adb:<serial> --instructions tests/example.dcua --context tests/context.md --debug --report reports/example.html
+
+# Launchable Android AVD
+droid-cua --avd avd:<avd-name> --instructions tests/example.dcua --config ci/droid-cua.json --debug --report reports/example.html
+
+# iOS Simulator
+droid-cua --llm-provider loadmill --cua-model loadmill-smart --platform ios --avd "<simulator-name>" --instructions tests/example.dcua --debug --report reports/example.html
+
+# Local web
+droid-cua --llm-provider loadmill --cua-model loadmill-smart --target web --browser chrome --session-mode fresh --instructions tests/example.dcua --debug --report reports/example.html
+
+# LambdaTest
+droid-cua --llm-provider loadmill --cua-model loadmill-smart --device-source lambdatest --platform android --device-name "<name>" --os-version "<version>" --app <app.apk> --instructions tests/example.dcua --debug --report reports/example.html
+
+# AWS Device Farm
+droid-cua --llm-provider loadmill --cua-model loadmill-smart --device-source aws-device-farm --platform android --device-name "<name>" --os-version "<version>" --app <app.apk> --instructions tests/example.dcua --debug --report reports/example.html
+
+# Direct OpenAI alternative
+droid-cua --llm-provider openai --cua-model gpt-5.4 --avd adb:<serial> --instructions tests/example.dcua --context tests/context.md --debug --report reports/example.html
+```
+
+Use `.ipa` and `--platform ios` for supported cloud iOS runs. Preserve existing config flags rather than replacing them with defaults.
+
+## Confirm the run with the user
+
+Before starting any test command, send the user a short, plain-language run plan and wait for explicit confirmation. Treat this as a product conversation, not a command preview. Do not infer that a request to run a test also confirms an automatically selected device, browser, or batch of tests.
+
+The run plan should briefly state:
+
+- What behavior or flow will be checked, and whether one test or several will run. Mention the test filename only when it helps identify the test.
+- Where it will run: the chosen device, simulator, or browser. If more than one viable target is available, present the human-readable choices and ask the user to choose.
+- Any user-visible consequence, such as launching an emulator, resetting a fresh browser session, or starting a metered cloud-device session.
+- That the agent will share progress screenshots and provide a report afterward.
+
+Do not include CLI flags, commands, provider or model names, credential/key names, config/context filenames, or internal log/report paths unless the user asks or one changes a decision they need to make. Do not paste the test source into the confirmation.
+
+Ask the user about every unresolved or ambiguous choice before running. If the plan is complete, ask for a clear go-ahead (for example, `Ready to run this?`). Start only after they confirm. If they change the tests, target, or other material run detail, show the revised plan and confirm it again.
+
+For example: `I’m ready to run the Chrome smoke test in a fresh local Chrome window. It will check that Chrome opens and then closes. I’ll share screenshots as it progresses and provide a report at the end. Ready to run this?`
+
+## Monitor and collect evidence
+
+Remain attached until the command exits and cloud cleanup finishes. Run the command through an interactive/pollable terminal mechanism so progress and new artifacts can be observed before it exits. Read terminal progress as it appears; do not treat a long model step as success or failure before completion.
+
+## Show live visual progress
+
+Use the screenshots already captured by `--debug` to make the run understandable while it is happening. This is a required user-facing behavior, not merely an artifact to inspect after the run. After the CLI prints `Debug logging enabled: <logs/execution-...>.jsonl`, new PNGs appear in that log file's sibling directory. Keep the CLI running in a pollable/background session and poll that directory while the test is running.
+
+For agents whose chat UI renders local Markdown images (including Cursor and Codex), send a separate progress message containing an absolute-path image, for example:
+
+```md
+Step 2/4: add the item to the cart
+
+![Live test progress](/absolute/path/to/logs/execution-.../0004_....png)
+```
+
+Do not put this Markdown only in a terminal command, tool argument, or hidden reasoning: it must be an actual user-visible chat update. Do not replace it by opening the final report.
+
+- After every completed executable instruction, send exactly one short progress update with that instruction and its screenshot (for example, `Step 2/4 complete: add the item to the cart`). An image path alone is not a visual update.
+- Screenshot filenames include `instruction-001`, `instruction-002`, and so on. Select the latest safe PNG for the completed instruction; prefer an end-of-turn or assertion screenshot over an input or click-preview frame. This connects each user-visible update to the matching script step even when the model took several actions to finish it.
+- Also show a frame immediately when the run is retrying, reconnecting, or fails. Do not stream every model action or repeat visually identical frames.
+- Do not show `preview_click` / aim-assist annotations unless they help explain an issue.
+- If the latest frame visibly exposes a secret or other sensitive user data, do not render it; provide a text-only progress update and wait for a safe frame.
+- Do not delay the test to collect screenshots. If no new frame exists during a long model call, report the current stage in text and keep polling.
+
+When the command completes, show the final safe screenshot in addition to the result summary, then provide a clickable link to the HTML report (or its absolute path when local links are unavailable). The report is the final artifact; the interim frames are progress updates, not a substitute for it.
+
+- Exit `0`: all requested tests passed.
+- Exit `1`: configuration, connection, execution, or assertion failure.
+- Exit `130`: interrupted run.
+- `--debug`: writes structured execution JSONL and adjacent screenshots under `logs/`.
+- `--report`: writes a self-contained HTML report. Prefer an explicit `.html` file path such as `reports/example.html` so the evidence location is unambiguous.
+
+After the run, verify that the report exists and resolve its absolute path. Open it for the user when the agent environment supports local-file opening and policy permits; otherwise provide a clickable local-file link or the absolute path so the user can open it directly.
+
+Report the outcome, failing instruction and first divergence when applicable, relevant error text, screenshot/debug/report paths, target, provider/model, and command with secret values omitted.
+
+## Classify the first divergence
+
+1. **Setup or authentication**: missing/invalid provider credential, dependency, license, browser, or executable. Return to onboarding and rerun only the failed check.
+2. **Target connectivity**: no device, unauthorized/offline ADB state, unavailable simulator, cloud credential/device/app problem, or lost session. Restore the same target, then rerun.
+3. **Test ambiguity or stale test knowledge**: instruction has multiple interpretations, relies on an unstable label, lacks a starting condition, or context contradicts the visible product. A minimal test/context correction is allowed.
+4. **Application regression**: the app crashes, displays an error, violates an explicit requirement, or consistently fails a stable assertion after correct setup. Stop and report a bug with evidence.
+5. **Transient execution**: temporary network, service, model, or timing failure without evidence of a deterministic product/test issue. Retry the unchanged targeted test once.
+
+## 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.
+
+Make one minimal change, explain why it corrects the test rather than hides a product defect, and rerun only the affected test. Allow at most two edit/rerun cycles. If it still fails, stop with the original and final evidence, changes attempted, and recommended owner/action.