@uipath/skills 1.195.0

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/interpretations/healing-agent-data.md

@@ -0,0 +1,277 @@
+# Healing Agent Data
+
+When Healing Agent is enabled and a UI automation activity fails, the system captures detailed recovery data. This feature describes how HA interacts with UI Automation at runtime, the data structure it produces, and how to gather and interpret that data.
+
+## How It Works
+
+1. A UI automation activity fails with a selector exception
+2. HA captures the current UI tree snapshot at the point of failure
+3. HA analyzes the snapshot and generates alternative selectors
+4. In **Self-Healing mode** — HA applies the best alternative and the activity retries automatically. If recovery succeeds, the job continues and recovery data is written as `RecoveryInfo`.
+5. In **Recommendations mode** — HA records the suggestions for later review. The activity still fails, but recovery data is written as `InferredRecoveryInfo`.
+6. Recovery data is written to the `healing-agent/` directory and accessible via Orchestrator API
+
+HA only works with selector-based UI automation activities. Image-only targeting is not supported for recovery.
+
+## Two-Tier Data Structure
+
+```
+healing-agent/
+  recovery-data-summary.json     # Index file (~15KB) — ALWAYS read first
+  uia/                           # Detailed recovery data
+    638955556313961579.json      # 600KB-4MB per file
+    638955558234567890.json
+```
+
+### Tier 1: Index File (recovery-data-summary.json)
+
+Small (~15KB), safe to read fully. Contains:
+- Job metadata (JobId, ProcessName, RobotName, timestamps)
+- List of all recovery entries with metadata
+- Activity names and workflow file references
+- URIs to detailed files in the `uia/` directory
+
+### Tier 2: Detailed Files (uia/*.json)
+
+Large (600KB-4MB each). **Never read entire files.** Use targeted extraction.
+
+Key paths:
+- `.Content.RuntimeInfo` — activity details, failed selector, error message, `ActivityRefId`
+- `.Content.AnalysisResult[0].AnalysisInformation` — strategies executed by Healing Agent (with Targets or Popups identified)
+- `.Content.AnalysisResult[0].OriginalException` — why the activity failed (its exception)
+- `.Content.AnalysisResult[0].Images` — base64 screenshots (~500KB, extract only when needed)
+
+## External Interference (Popups)
+
+HA can detect external interferences that blocked the automated application — windows overlapping the target app, HTML popups, or native browser popups (e.g., JavaScript `alert` dialogs).
+
+- **External windows** — other application windows that appeared over the automated app. HA minimizes them to restore access.
+- **HTML popups** — in-page overlays or dialogs within the browser. HA closes them.
+- **Native browser popups** — JavaScript `alert`, `confirm`, `prompt` dialogs. HA dismisses them.
+
+### Where to find popup data (agent-internal)
+
+Popup recoveries are in `RecoveryInfo[].RecoveredExternally.Recoveries[]`. Each entry may contain:
+- `ClickTarget` — the selector HA used to dismiss an HTML popup (browser popups only)
+- `ClickTargetImage` — screenshot of the clicked dismiss element
+- `Image` — screenshot of the popup itself
+
+### Presenting popup findings to the user
+
+Tell the user that a popup was detected and HA dismissed it. Do NOT expose field names or raw popup data. Example:
+- Say "A popup appeared over the application and Healing Agent dismissed it to continue" — NOT "RecoveredExternally.Recoveries[0] contains a ClickTarget"
+
+### Fix for popups
+
+Do NOT attempt to edit the workflow to handle popups programmatically. Instead, suggest the user apply the fix from **Studio Desktop Recovery Panel**, which can integrate HA's popup handling into the workflow.
+
+## Deterministic Fixes (healing-fixes.json)
+
+When HA successfully identifies a fix, it's written to `healing-fixes.json` at the job cache root (next to `job-info.json`, `logs.txt`, `trace.json`).
+
+Each entry contains:
+- **activityRefId** — unique activity identifier, maps to XAML `IdRef`
+- **activityName** — display name of the activity
+- **workflowFile** — which .xaml file contains the activity
+- **source** — `RecoveryInfo` (HA applied fix at runtime and it worked) or `InferredRecoveryInfo` (HA inferred fix from UI tree after failure)
+- **fixes** — array of fix objects:
+  - `update-target` — replace the activity's selector with HA-recommended one
+  - `dismiss-popup` — add a Click activity to dismiss a popup before the failing activity
+
+## Activity Matching: HA Data → XAML
+
+The `ActivityRefId` from HA data maps directly to the `sap2010:WorkflowViewState.IdRef` attribute in XAML. This is a unique match within a workflow.
+
+Matching methods (in preference order):
+1. **ActivityRefId → IdRef** (preferred) — unique, unambiguous
+2. **ActivityName + WorkflowFile** (fallback) — may be ambiguous if duplicate display names exist
+3. **Line number / position** (last resort) — fragile, breaks if file is edited
+
+## XAML Selector Encoding
+
+When editing selectors in XAML, apply XML encoding in this order:
+1. `&` → `&` (FIRST — otherwise it corrupts other encodings)
+2. `<` → `&lt;`
+3. `>` → `&gt;`
+4. `'` → `&apos;`
+5. `"` → `&quot;`
+
+## How to Check if HA is Enabled
+
+Read the `AutopilotForRobots` field from job info. All three conditions must be true:
+
+1. `AutopilotForRobots` field exists and is not null
+2. `AutopilotForRobots.Enabled` is `true`
+3. `AutopilotForRobots.HealingEnabled` is `true`
+
+**Do NOT rely on the legacy `EnableAutopilotHealing` field** — it's a computed boolean that can be `false` even when HA is properly enabled. Always use `AutopilotForRobots` as the authoritative source.
+
+If HA is disabled, UI failure troubleshooting is severely limited — no UI tree snapshots, no alternative selectors, no recovery detections. Enabling HA is the single highest-impact configuration change for improving UI failure troubleshooting.
+
+## How to Gather HA Data
+
+1. **Check if healing-fixes.json exists** — this is the highest-value file. If it exists and has entries, the fix is already known with high confidence. Check this before reading anything else.
+
+2. **Read recovery-data-summary.json** — always read this first (~15KB, safe to read fully). It gives you the map to everything in the `uia/` directory.
+
+3. **Choose image handling** — steps 3a and 3b are mutually exclusive. Decide before processing:
+
+   - **3a. Strip images** (default) — if screenshots are NOT needed for this investigation, run the post-processing script to remove base64 image data. This reduces file sizes from ~4MB to ~50KB and makes them safe to read:
+
+     ```powershell
+     # Windows (PowerShell)
+     pwsh scripts/strip-ha-images.ps1 -Path uia/
+     ```
+
+     ```bash
+     # Linux/macOS
+     bash scripts/strip-ha-images.sh uia/
+     ```
+
+   - **3b. Preserve images** — if visual confirmation IS needed (e.g., to show the user the UI state at failure), do NOT run the strip script. Instead, extract screenshots selectively — images are base64 encoded, ~500KB each. Only read the last image (most recent UI state).
+
+   Once images are stripped, they cannot be recovered. If unsure, preserve them.
+
+4. **Extract targeted fields from uia/*.json** — for targeted extraction:
+
+```bash
+# Get the ActivityRefId (critical for XAML matching)
+jq -r '.Content.RuntimeInfo.ActivityRefId' uia/638955556313961579.json
+
+# Get just the failure reason
+jq -r '.Content.AnalysisResult[0].OriginalException' uia/638955556313961579.json
+
+# Get detections
+jq -r '.Content.AnalysisResult[0].AnalysisInformation[0]' uia/638955556313961579.json
+```
+
+Alternative with grep when jq isn't available:
+```bash
+grep -A 3 '"ActivityRefId"' uia/638955556313961579.json
+grep -A 3 '"OriginalException"' uia/638955556313961579.json
+```
+
+## Cross-Job Comparison
+
+Do NOT assume that other job runs of the same process are relevant if the package version differs. A different version means the workflow may have changed — selectors, activities, and recovery behavior could all be different. Treat each package version as a separate process for troubleshooting purposes.
+
+Only compare across job runs when:
+- The package version is **identical** between the jobs being compared
+- OR the user **explicitly asks** to check similar jobs across versions
+
+If the user asks to verify similar jobs of the same process, note the version difference in findings and flag that conclusions may not transfer across versions.
+
+## How to Interpret HA Data
+
+### Strategy Classification (agent-internal — NEVER show to user)
+
+Strategies in `AnalysisInformation` are classified by their name prefix:
+- **Alternative target strategies** — name starts with `FindAlternative` or is `ReuseTargetFaultAnalyzer`. These attempt to find a replacement UI element for the failed selector.
+- **Other strategies** — everything else (e.g., popup detection).
+
+### Source Types and Recovery Status
+
+- **RecoveryInfo** with `RecoverySuccessful: true` — HA applied this fix at runtime and the activity succeeded. This is a **proven fix**.
+- **RecoveryInfo** with `RecoverySuccessful: false` — HA attempted to apply a fix at runtime but the activity still failed. The suggested alternative did not work. Do NOT offer this as a fix.
+- **InferredRecoveryInfo** — HA was in **recommendation-only mode** (self-healing disabled). `RecoverySuccessful` will always be `false` because HA did not retry the activity — it only analyzed the UI tree and inferred a possible alternative.
+
+### Detections Without Recovery Entries
+
+HA may find alternative targets or popups in `AnalysisResult` that do NOT appear in `RecoveryInfo` or `InferredRecoveryInfo`. This happens when:
+
+- **Self-healing was enabled (RecoveryInfo path):** HA uses a voting mechanism across strategies — it selects the alternative target that intersects the most with the other strategies' results. If no consensus exists (strategies found different, conflicting alternatives), HA does not recommend anything to avoid false positives. The detections still exist in `AnalysisResult` but no recovery entry is written.
+- **Recommendation-only (InferredRecoveryInfo path):** Same voting logic applies. HA analyzed the UI tree but strategies disagreed, so no recommendation was produced.
+
+Only fall back to `AnalysisResult` in the detailed `uia/*.json` files if `RecoveryInfo` and `InferredRecoveryInfo` are empty or don't contain useful information. When reading `AnalysisResult`, be aware that strategies may have entries with empty detections (no targets or popups found) — skip those and only consider strategies that actually found something.
+
+If `AnalysisResult[].AnalysisInformation[]` contains non-empty detections but `RecoveryInfo`/`InferredRecoveryInfo` are empty, tell the user that Healing Agent detected possible alternatives but its internal voting mechanism could not reach consensus, so no fix was recommended. Do NOT offer to apply anything from `AnalysisResult` — these are unreliable.
+
+### Applying Fixes — MUST Ask the User
+
+When a fix is available, you MUST use `AskUserQuestion` to ask the user whether they want you to apply it. Do NOT skip this step. Do NOT just describe the fix — explicitly ask.
+
+When presenting the fix, first print the selectors as plain text output (NOT inside `AskUserQuestion` options or previews — XML selectors don't render correctly there). Then ask the question separately.
+
+**Step 1 — Print selectors as text:**
+
+```
+Failed selector:
+<selector content from FailedResolvedTarget.PartialSelector or FuzzyPartialSelector>
+
+Recovered Partial selector:
+<selector content from the chosen detection's PartialSelector>
+
+Recovered Fuzzy selector:
+<selector content from the chosen detection's FuzzyPartialSelector>
+```
+
+**Step 2 — Ask the user** (via `AskUserQuestion`, with no previews):
+
+**If RecoveryInfo with RecoverySuccessful: true:**
+- Tell the user the fix was proven at runtime
+- Ask which recovered selector they want to apply (Partial or Fuzzy)
+
+**If InferredRecoveryInfo with fix suggestions:**
+- Warn the user that HA was in recommendation-only mode (self-healing was not enabled), so this fix was never actually tested at runtime and there's no guarantee it will work
+- Ask which recovered selector they want to apply (Partial or Fuzzy)
+
+**If no fix is available** (RecoverySuccessful: false with RecoveryInfo, no suggestions in InferredRecoveryInfo, or detections without recovery entries):
+- Do NOT offer to apply anything. Proceed with manual investigation.
+
+### Failure Reasons
+
+The `TargetAnalysis.FailureReason` field explains why the original selector failed:
+- Element attribute changed (name, id, class)
+- Element moved to a different position in the UI tree
+- Element no longer exists (removed from application)
+- Multiple elements match the selector (ambiguous)
+
+## Applying HA Fixes
+
+When `healing-fixes.json` contains actionable fixes, present the findings to the user and ask which fix to apply. The project path is needed — if not already known, ask the user to provide it.
+
+### Applying `update-target` Fixes
+
+1. Match the XAML activity by `ActivityRefId` → `IdRef` attribute (unique within workflow)
+2. Check if the `uia-improve-selector` skill is available locally:
+   ```
+   Glob: pattern="**/uia-improve-selector/USAGE.md" path="{PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/skills/"
+   ```
+3. **If the skill exists:** ask the user if they want to improve the selector using it. If yes, read `<PROJECT_DIR>/.local/docs/packages/UiPath.UIAutomation.Activities/skills/uia-improve-selector/USAGE.md`, pick the appropriate invocation form for this context, run the staging CLI command from that form to produce `Target_Definition.json`, spawn a subagent with the Agent tool to run the skill with `--mode recover` against the staged folder, then run the write-back CLI command from the same form to persist the recovered selector.
+4. **If the skill does not exist:** update the activity's selector in XAML directly with the HA-recommended selector from `enhancedTarget`. Apply XML encoding per the XAML Selector Encoding rules above.
+5. Validate: `uip rpa validate --file-path "<WORKFLOW_FILE>" --output json`
+
+### Applying `dismiss-popup` Fixes
+
+1. Ask the user if they want to add a Click activity before the failing activity to dismiss the detected popup
+2. If yes, use the `uip rpa` workflow skill to create the Click activity:
+   - Get the Click activity template: `uip rpa activities get-default-xaml --activity-class-name "UiPath.UIAutomationNext.Activities.NClick" --output json`
+   - Set the target on the Click activity using the `clickTarget` from the HA fix entry (this contains the selector and image for the popup dismiss element)
+   - Insert the Click activity immediately before the failing activity in the XAML (match by `ActivityRefId` → `IdRef`)
+3. The Click activity must be inside a `Use Application/Browser` (`NApplicationCard`) scope — verify the failing activity already has one
+4. After inserting the Click activity, verify it is correctly configured:
+   - Run `uip rpa validate --file-path "<WORKFLOW_FILE>" --output json` to confirm the workflow still compiles with zero errors
+   - If validation errors appear on the new Click activity, troubleshoot and fix them before continuing (common issues: missing target, activity outside NApplicationCard scope, XML encoding errors in the selector)
+   - Tell the user the inserted activity's `IdRef` (`<NEW_CLICK_IDREF>`) and ask them to open the workflow in Studio to visually confirm placement and target
+
+## Presentation — No Internal Fields
+
+**NEVER present internal field names, JSON paths, strategy names, debug file structure, or raw data keys to the user.** This includes tables, lists, or any format that exposes internals. The user does not need to know about `ActivityRefId`, `AnalysisResult`, `RuntimeInfo`, `AnalysisInformation`, `OriginalException`, `RecoverySuccessful`, strategy names like `FindAlternativeTextAttributeTargetStrategy`, or any other internal key.
+
+Do NOT show tables of detections, strategy names, or raw analysis results. Translate everything.
+
+Do NOT tell the user which strategy or method HA used to recover the target. It is enough to say that HA found a fix.
+
+Examples:
+- Say "The activity **Click 'Submit'** in **Main.xaml** failed because the selector no longer matches" — NOT "ActivityRefId 12345 in RuntimeInfo shows SelectorNotFoundException"
+- Say "Healing Agent found an alternative for this element" — NOT "FindAlternativeTextAttributeTargetStrategy with Confidence 0.95" or "matched by text content"
+- Say "The button was renamed from 'Submit' to 'Send'" — NOT "The aaname attribute changed in the enhanced target"
+- Say "Healing Agent analyzed 3 failed activities and found fixes for 2 of them" — NOT a table of AnalysisInformation entries
+
+Internal field names exist in this document so the agent knows where to look in the JSON. They are never for the user.
+
+## Prerequisites
+
+- Healing Agent must be enabled on the process (`AutopilotForRobots.Enabled: true`, `AutopilotForRobots.HealingEnabled: true`)
+- Robot must have connectivity to Semantic Proxy and LLM Gateway
+- Activity must use selector-based targeting (HA doesn't support image-only activities for recovery)

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/investigation_guide.md

@@ -0,0 +1,25 @@
+# UI Automation Investigation Guide
+
+## Data Correlation
+
+Before using any fetched data, verify it matches the user's reported problem:
+
+- **Activity** — the faulted activity namespace and name match the reported failure
+- **Selector** — the selector in evidence corresponds to the actual target element the user described
+- **Application** — the target application (name, version, technology) matches the user's environment
+- **Workflow** — the error originates from the correct workflow file / activity in the project
+- **Timestamp** — the failure occurred during the time window the user reported
+
+If the data doesn't match: **discard it**. Do NOT use unrelated data as a proxy. Report the mismatch and ask for clarification.
+
+## Testing Prerequisites
+
+When testing hypotheses for UI Automation issues, gather and verify these before drawing conclusions:
+
+1. **Activity type and namespace** — identify the exact activity that faulted (e.g., `UiPath.UIAutomationNext.Activities.NClick` vs `UiPath.Core.Activities.Click`)
+2. **Selector definition** — read the actual selector from the workflow source or error details; don't rely on summaries
+3. **Target application state** — verify the application was running and the expected screen/page was visible at time of failure
+4. **Healing Agent status** — if relevant, check whether Healing Agent is enabled, whether recovery data exists
+5. **Execution context** — check if running attended vs unattended, screen resolution, RDP session state — these affect UI element visibility
+6. **Package version** — confirm `UiPath.UIAutomation.Activities` package version; behavior differs across versions
+7. **Enclosing scope container configuration** — for activities inside a scope container (`NApplicationCard`, `NBrowser`, `Use Application/Browser`, `NWindow`, `Attach Window`, `Attach Browser`, etc.), open the workflow XAML and capture the container's `AttachMode`, `OpenMode` (defaults to `IfNotOpen` when absent), and `TargetApp.{Selector,Url}` values. The scope container determines which application instance/page the inner selector resolves against — a misconfigured scope makes a structurally correct selector fail (e.g., card attaches to an unintended existing tab via `AttachMode=ByInstance` + default `OpenMode=IfNotOpen` + a loose `TargetApp.Selector`). Do not confirm a selector-failure hypothesis before naming the scope container's configuration.

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/overview.md

@@ -0,0 +1,39 @@
+# UI Automation
+
+Activities for interacting with desktop and web application UIs. Robots use selectors (XML descriptors of UI elements) to find and interact with buttons, text fields, tables, and other controls.
+
+## How Selectors Work
+
+A selector is an XML string that describes the path from the application window to the target UI element:
+
+```xml
+<html app='chrome.exe' title='Invoice Portal' />
+<webctrl tag='BUTTON' aaname='Submit Invoice' />
+```
+
+When a robot executes a UI activity (Click, Type Into, Get Text, etc.), it uses the selector to locate the element in the live UI tree. If the element can't be found — because the UI changed, the element was renamed, or the layout shifted — the activity throws a `SelectorNotFoundException`.
+
+## Key Activity Types
+
+- **Click / NClick** — click a UI element
+- **Type Into / NTypeInto** — type text into an input field
+- **Get Text / NGetText** — extract text from a UI element
+- **Set Text** — set the value of an input field
+- **Check App State** — wait for a UI element to appear or disappear
+- **Element Exists** — check if a UI element exists without interacting
+- **Take Screenshot** — capture a screenshot of the application
+
+## Exception Types
+
+- **SelectorNotFoundException** — the selector didn't match any element in the UI tree. Most common failure.
+- **UiElementNotFoundException** — UI element lookup failed (similar to selector not found, different internal path)
+- **ElementNotInteractableException** — element was found but can't be clicked/typed into (hidden, disabled, covered by overlay)
+- **UiNodeDisabledElementException** — element was found but is disabled and the activity's `AlterIfDisabled` property is not `True`. Driver HRESULT `E_UINODE_CANNOT_ALTER_DISABLED_ELEM` (0x8004027D). Raised by interaction activities `NClick`, `NTypeInto`, `NSetText`, `NCheck`, `NSelectItem`, `NSAPClickPictureOnScreen`.
+- **NodeNotFoundException** — DOM or UI tree node missing
+- **TimeoutException** — activity exceeded its wait time (ambiguous — could be UI or non-UI)
+- **ImageOperationException** — image-based UI automation failure
+- **ScreenScrapingException** — screen scraping activity failure
+
+## Features
+
+- **Healing Agent Data** — recovery data captured when HA is enabled and activities fail → [interpretations/healing-agent-data.md](./interpretations/healing-agent-data.md)

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/playbooks/disabled-element.md

@@ -0,0 +1,81 @@
+---
+confidence: high
+---
+
+# Disabled Element — AlterIfDisabled Not Enabled
+
+## Context
+
+A UI Automation Next interaction activity located its target element, but the element's `disabled` property/attribute was set, and the activity's `AlterIfDisabled` property was not `True`. The driver aborts the operation rather than acting on a disabled element.
+
+Applies to every UIAutomationNext interaction activity that exposes `AlterIfDisabled`:
+
+- `NClick`
+- `NTypeInto`
+- `NSetText`
+- `NCheck`
+- `NSelectItem`
+- `NSAPClickPictureOnScreen`
+
+What this looks like:
+
+- Exception class: `UiPath.UIAutomationNext.Exceptions.UiNodeDisabledElementException`
+- Friendly message: `The target element is disabled. Operation canceled.`
+- HRESULT: `0x8004027D` (`E_UINODE_CANNOT_ALTER_DISABLED_ELEM`)
+- Stack origin: `UiInputService.<Click|Type|SetText|Check|Select>Async` → `DriverServiceCore.WrapComAsync` → `ExceptionExtensions.ThrowFriendly`
+- Activity duration is short (sub-second to a few seconds) — the failure is NOT a timeout. The element was found, then rejected.
+- Selector resolved successfully (no `NodeNotFoundException` / `SelectorNotFoundException` in the same trace).
+
+This exception is specifically about the target element's own disabled property. A page overlay that *covers* the element produces a different error (click-intercepted / not-interactable / timeout), not this one. If the agent is tempted to infer "an overlay disabled the button," verify against the Healing Agent data — without HA popup evidence, that inference is unsupported.
+
+What to look for:
+
+- Confirm the exception class is `UiNodeDisabledElementException`. If the exception is `SelectorNotFoundException`, `UiElementNotFoundException`, `NodeNotFoundException`, or `TimeoutException` → use the matching `selector-failure-*.md` or `timeout-issue.md` playbook instead. The element being found is the entry condition for this playbook.
+- Identify the faulting activity name and its parent container (`NApplicationCard`, `Use Browser`, `Attach Window`). The `AlterIfDisabled` setting lives on the leaf activity, not the container.
+- Inspect the `InputMode` (or `Input Method`) of the leaf activity. If it is `HardwareEvents`, `AlterIfDisabled` is inert — see Resolution.
+- Inspect any Healing Agent recovery data on the job for popup detections.
+
+## Investigation
+
+1. From the failed job, capture the exception class, friendly message, activity name, and workflow file (e.g., `ClickCase.xaml` → `NClick "Click 'Submit'"`).
+2. Open the workflow source and locate the failing activity by its name or `IdRef`.
+3. Read the activity's `AlterIfDisabled` property. Default is unset (`null`), which the driver treats as `false`.
+4. Read the activity's `Input Mode` (Selector, Image, Hardware Events, Background, Native, Driver). Note whether it is `HardwareEvents`.
+5. Check whether Healing Agent ran on this job, and in which mode (self-healing vs. recommendation-only). See [interpretations/healing-agent-data.md](../interpretations/healing-agent-data.md).
+6. If HA ran, check whether it detected a popup or external interference covering the target:
+   - Self-healing mode: look at `RecoveryInfo[].RecoveredExternally.Recoveries[]` and the run-level `RecoverySuccessful` / `ConsumedReason`.
+   - Recommendation-only mode: look at `InferredRecoveryInfo` and `AnalysisResult[].AnalysisInformation` for popup detections.
+7. Read the activity's `Target` selector and the parent scope's `TargetApp.Url` to record what page the activity ran against.
+
+## Resolution
+
+### Decision tree
+
+Walk this tree from the top. Stop at the first branch that matches.
+
+1. **Is the leaf activity's `Input Mode` (or inherited mode) `HardwareEvents`?**
+   - YES → branch (A) below. `AlterIfDisabled` is inert in Hardware Events.
+   - NO → continue.
+
+2. **Did Healing Agent run on this job AND detect a popup / external interference that it could not clear?**
+   - HA self-healing mode AND popup was detected AND HA's dismiss attempt failed (`RecoverySuccessful = false`, popup still blocked the click) → branch (B).
+   - HA recommendation-only mode AND popup was detected in `InferredRecoveryInfo` / `AnalysisResult` (HA only inferred, did not attempt dismissal) → branch (C).
+   - HA did not run, OR HA ran and found no popup, OR HA ran and successfully cleared the popup (in which case the job would not have faulted with this exception) → continue.
+
+3. **Default (no HardwareEvents quirk, no HA-detected blocking popup) → branch (D):** Set `AlterIfDisabled = True` on the failing activity.
+
+### Branches
+
+- **(A) `Input Mode = HardwareEvents`:** `AlterIfDisabled` cannot help — the property does not apply to Hardware Events. Switch `Input Mode` to a driver-based mode that supports `AlterIfDisabled` (`Selector`, `Default`, `Driver`, `ChromiumAPI` where supported by the target tech), then apply branch (D). Do not leave the workflow as Hardware Events + disabled target — the click lands at the screen coordinate but the application ignores it, producing silent failures downstream rather than a typed exception.
+
+- **(B) HA self-healing tried to dismiss a popup and failed:** The popup is the originating blocker. Do NOT set `AlterIfDisabled = True` — forcing the click would land on the popup, not the intended target. Fix the popup: inspect `RecoveryInfo[].RecoveredExternally.Recoveries[]` for the `ClickTarget` HA attempted and why it failed (popup not present in DOM, dismiss selector stale, popup re-appears after dismiss). Add a deterministic dismissal step to the workflow before the failing activity — typically a Click on the popup's actual close button, or apply the fix via Studio Desktop Recovery Panel.
+
+- **(C) HA recommendation-only detected a popup:** HA inferred a popup over the target but did not attempt to dismiss it (recommendation-only mode). Do NOT set `AlterIfDisabled = True`. Surface the popup to the user (per [interpretations/healing-agent-data.md](../interpretations/healing-agent-data.md) presentation rules) and apply HA's `dismiss-popup` fix from `healing-fixes.json` via Studio Desktop Recovery Panel — or, if no fix entry exists, add a Click activity targeting the popup's dismiss button before the failing activity.
+
+- **(D) Default — set `AlterIfDisabled = True` on the failing activity:** The element's `disabled` property is the abort cause and no popup is blocking the target. Add or update `AlterIfDisabled="True"` on the leaf activity's XAML element (or via Studio's Properties panel). Verify `Input Mode` is not `HardwareEvents` (branch A handles that). Acceptable input modes for this fix: `Selector`, `Default`, `Driver`, `ChromiumAPI`.
+
+  This is the right fix for the broad case where the target's `disabled` attribute is set at click time — whether the disable is permanent (read-only field, advisory control), part of the normal UI lifecycle (button enables only on form-valid), or because an upstream step did not run. In all of those, `AlterIfDisabled = True` instructs the driver to act on the element as found, which is what the exception is asking for.
+
+  Optional preventive add-ons (in addition to setting `AlterIfDisabled = True`):
+  - If the disable is from a missing upstream step (e.g., the workflow forgot to type a query into a search box before clicking a dependent button), add that upstream step. `AlterIfDisabled = True` still belongs on the leaf as a defense-in-depth — it removes the abort even if the upstream step degrades.
+  - If the workflow is sensitive to UI-version drift, keep Healing Agent enabled so future popup interferences get captured.

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/playbooks/healing-agent-no-license.md

@@ -0,0 +1,109 @@
+---
+confidence: high
+---
+
+# Healing Agent — No License / Heals Available
+
+## Context
+
+Healing Agent is enabled on the run but cannot perform recovery because the tenant has no Healing Agent license consumables (Heals, Test Heals, Platform Units, or Agent Units) available — or has the wrong **type** for the runtime. The activity faults with a standard selector exception, HA emits an explicit "no license" error in the robot log, and no diagnostic data is produced.
+
+### Licensing model — the discriminator
+
+HA license consumption depends on two axes, not just one:
+
+| Axis | Values | Effect |
+|------|--------|--------|
+| **License type** | `Flex` / `Unified` | Flex can only assign Heals; Unified can assign both Heals **and** Test Heals |
+| **RuntimeType of the job** | **Test set** (→ **Test Heals** required): `AppTest`, `TestAutomation`, `ServerlessTestAutomation`, `AutomationCloudTestAutomation`, `PerformanceTest`. **Non-Test set** (→ regular **Heals** required) — commonly observed values include `Production`, `NonProduction`, `Development`, `Attended`, `Unattended`, `StudioPro`, `Studio`. Any value not in the Test set routes to regular Heals — match by Test-set membership, not by enumerating Non-Test names. | Orchestrator returns RuntimeType on the job; HA picks the pool from it |
+
+Consumption rates after the bundled 5K heals are exhausted: **3 Platform Units per heal (Unified)** or **15 Agent Units per heal (Flex)**. One heal covers one unique recovered element per job — re-running the same element inside a loop is still one charge. A new job re-charges.
+
+### What this looks like (primary, deterministic)
+
+- A robot log entry at level `Error` containing the substring **`No available license / Agentic units to perform healing analysis and recovery`**. Full template (display name varies): `"'<activity-display-name>' activity recovery failed. No available license / Agentic units to perform healing analysis and recovery."` Canonical English message; localized robots emit the equivalent translation at the same log level. Match the English substring first via `uip or jobs logs`.
+- The operation code in the log line distinguishes the pool: **`HealingAgent.Test`** = Test Heals requested, **`HealingAgent`** = regular Heals requested. App Insights / backend logs surface this as `CanConsume=False for orgId=..., tenantId=... and licenseCode:HealingAgent.Test` (or `HealingAgent`).
+
+### Corroborating signals (when the log line is ambiguous, missing, or localized)
+
+- `AutopilotForRobots.Enabled = true` AND `AutopilotForRobots.HealingEnabled = true` on the job
+- Job log contains `"Healing agent analysis and recovery are enabled for current job."` near start of execution, but no subsequent HA recovery activity
+- HA diagnostic archive is empty — `uip or jobs healing-data <job-key> -o <out>.zip` produces a 22-byte ZIP containing zero entries (`PK\x05\x06` end-of-central-directory record only)
+- `uip or licenses info` shows `Data.Allowed.AgentService == 0` and `Data.LicensedFeatures: []` (or HA features absent)
+- App Insights / backend: `Could not find any enabled consumption pools for [org-id]`
+- Job-level `Info` contains the underlying selector exception (`NodeNotFoundException`, `SelectorNotFoundException`, etc.) — **not** the license message. License diagnosis lives in the robot log, not in `jobs get`.
+
+### What can cause it
+
+1. **No Healing Agent entitlement on the tenant.** Subscription does not include HA on this tenant. Applies across all plans. Discriminator is `Allowed.AgentService == 0`, not the plan name. Flex Advanced and Unified Enterprise bundle 5K heals; other tiers require the HA Add-On.
+2. **Heals/Test Heals pool mismatch.** Run executes on a Test RuntimeType (e.g., the job uses an Unattended-Test robot or runs from Test Manager / Test Cloud) but the tenant only has regular Heals allocated. Even with thousands of regular Heals and bundled trial Heals, a Test runtime with 0 Test Heals will fail. **Flex tenants cannot assign Test Heals at all** — only Unified can.
+3. **UIA package version behavior.** **UIA 25.10.22 and lower always consumes Heals regardless of RuntimeType** — it does not differentiate. **UIA 25.10.23 and above** correctly routes Test runtimes to Test Heals. This means a Flex tenant running tests on UIA 25.10.22 succeeds (consumes Heals); upgrade to 25.10.23+ and the same job fails with this error.
+4. **Preview-vs-GA version mismatch.** UIA 24.10.x was the Public Preview of HA and lacked proper license validation. UIA 25.10.x is GA and enforces it. A job that "worked before" on 24.10.x and breaks after upgrade to 25.10.x is hitting GA enforcement, not a regression — the preview was unlicensed and is no longer supported.
+5. **Heals purchased but not assigned to this tenant.** Heals exist at the organization level but are not allocated to the specific tenant. Manifests as `Could not find any enabled consumption pools` in App Insights and `CanConsume=False` in backend logs.
+6. **Consumption pool not enabled.** Tenant has the entitlement and allocation but the pool itself is disabled.
+7. **Pool exhausted.** Allocation is non-zero but fully consumed for the billing period.
+
+### Distinguish from related playbooks
+
+- **`no-recovery-data.md`** — HA is licensed but produced no data for other reasons (connectivity, image-only target, classic activities). Inspect `licenses info`. If `Allowed.AgentService == 0` OR the robot log carries the "No available license / Agentic units" line, this playbook applies. If both checks come back negative, fall back to `no-recovery-data.md`.
+- **`selector-failure-healing-disabled.md`** — that playbook requires `AutopilotForRobots.HealingEnabled = false`. Here HealingEnabled is `true` but the run still produced no data because HA refused to run.
+- HA-no-license fires regardless of job type. Attended, Unattended, Unattended-Test, and TestAutomation runs all surface the same log line when entitlement is missing or the wrong pool is targeted. The `Type` and RuntimeType only determine which consumable pool (Heals vs. Test Heals) is the relevant fix.
+
+## Investigation
+
+1. **Fetch error-level robot logs.** `uip or jobs logs <job-key> --level Error --output json`. Search case-insensitively for the substring `No available license` (or `Agentic units to perform healing`). A match at level `Error` is **the** deterministic signal — record the full log line verbatim (it includes the activity display name in single quotes) and check the operation code:
+   - `HealingAgent.Test` → Test Heals were requested. Job ran on a Test RuntimeType. Fix targets the Test Heals pool.
+   - `HealingAgent` → regular Heals were requested. Fix targets the Heals pool.
+
+   Then proceed to Resolution. If no match, continue to step 2. `jobs logs` is cross-folder; no `--folder-path` flag needed.
+
+2. **Get the faulted job.** `uip or jobs get <job-key> --output json`. Confirm `State = Faulted` and read:
+   - `AutopilotForRobots.Enabled` and `AutopilotForRobots.HealingEnabled` — both must be `true` for this playbook to apply.
+   - `Type` and the underlying RuntimeType. Test RuntimeTypes (`AppTest`, `TestAutomation`, `ServerlessTestAutomation`, `AutomationCloudTestAutomation`, `PerformanceTest`) consume Test Heals; everything else consumes Heals.
+   - `errorCode = "Robot"` is the typical job-level field; `jobError` is often empty `{}` — actionable detail lives in logs, not in `jobError`.
+
+   `jobs get` is cross-folder; no `--folder-path` flag needed.
+
+3. **Fetch the HA diagnostic archive.** `uip or jobs healing-data <job-key> -o <out>.zip`. A **22-byte file is an empty ZIP** (zero entries) — HA produced no data. Combined with HA being enabled on the job, this confirms HA refused to run. `healing-data` takes the job key as a positional argument and `-o` for the output path; no `--folder-path` flag exists.
+
+4. **Check the UIA package version of the failing process.** Determine which UIAutomation package version the process is pinned to. If the project is local, read `project.json`. Two thresholds matter:
+   - **< 25.10.x** → likely on UIA 24.10.x preview. Preview HA is unsupported on GA tenants; upgrade is the fix regardless of license state.
+   - **25.10.22 and below** → does not differentiate Heals vs Test Heals (always consumes Heals). Symptom: a Test-runtime job fails on a Flex tenant after upgrading from 25.10.22 to 25.10.23+. This is expected GA behavior, not a regression.
+   - **25.10.23+** → correctly routes by RuntimeType.
+
+5. **Check tenant license allocation.** `uip or licenses info --output json`. Read these fields:
+   - `Data.SubscriptionPlan` — informational only. Commonly observed string values: `COMMUNITY`, `TRIAL`, `PRO_TRIAL`, `STANDARD`, `ADVANCED`, `ENTERPRISE` (and trial variants). **The field reports the tier label only — it does NOT encode the license type (Flex vs Unified).** HA bundling depends on BOTH axes: Flex bundles HA on the Advanced tier (5K Heals); Unified bundles HA on the Enterprise tier (5K Heals). A bare `ENTERPRISE` plan could be Flex Enterprise (no bundle) or Unified Enterprise (bundles HA) — `licenses info` cannot tell you which. Therefore, even an `ENTERPRISE` tenant can have `Allowed.AgentService = 0` if the HA Add-On is not provisioned. **Never branch on `SubscriptionPlan` alone** — always read `Allowed.AgentService` and `LicensedFeatures` for the deterministic signal.
+   - `Data.Allowed.AgentService` — must be `> 0` for HA to run on this tenant. `== 0` confirms the missing-entitlement case.
+   - `Data.Used.AgentService` — if `Used >= Allowed` and `Allowed > 0`, the pool is exhausted.
+   - `Data.LicensedFeatures` — should list HA-related features; an empty array `[]` means no HA entitlement on this tenant.
+
+   Note: `licenses info` reports aggregate `AgentService` units. It does **not** distinguish Heals from Test Heals separately — the operation code in step 1 is the only CLI-accessible signal for which pool was requested. Per-pool inspection requires the Automation Cloud UI.
+
+6. **If steps 1–5 are inconclusive** (no log line, `licenses info` looks normal, healing-data is still empty), the likely cause is pool-not-assigned-to-tenant or pool-not-enabled, and **there is no `uip` command to inspect this**. Verify in the Automation Cloud UI: Admin → Licenses → Consumables. Confirm the Heals (or Test Heals) pool is allocated to this tenant and the pool is enabled.
+
+## Resolution
+
+Pick the branch that matches the operation code from step 1 and the `licenses info` reading from step 5.
+
+- **Operation code `HealingAgent` and `Allowed.AgentService == 0` with `LicensedFeatures: []` (missing entitlement):** the tenant subscription does not include Healing Agent. Acquire the HA Add-On for this tenant via the Automation Cloud admin portal, or move the tenant to a plan that bundles Heals (Flex Advanced, Unified Enterprise). Plan name alone does not predict the fix — every plan can be entitled or not based on the add-on.
+
+- **Operation code `HealingAgent` and `Allowed.AgentService > 0` and `Used.AgentService >= Allowed.AgentService` (pool exhausted):** allocate additional Heals consumables to the tenant in the admin portal (Admin → Licenses → Consumables) or wait for the billing period to reset. After the bundled 5K is consumed, Unified tenants spend 3 Platform Units per heal and Flex tenants spend 15 Agent Units per heal — verify the unit pool covering overflow has capacity.
+
+- **Operation code `HealingAgent.Test` (Test runtime):** the consumable is **Test Heals**, not regular Heals. Required entitlements:
+  - **Unified tenant:** Test Heals via the Test Healing Agent Add-On.
+  - **Flex tenant:** Flex **cannot** assign Test Heals. Options: (a) migrate to Unified to access Test Heals, (b) switch the failing job to an Unattended (non-test) robot if the workflow does not require Test Manager features, or (c) **temporarily pin UIA to 25.10.22 or lower** so the activity consumes Heals regardless of RuntimeType (workaround only — 25.10.23+ will enforce Test Heals on Test runtimes). Verify Tester License + Test Healing Add-On + Test Heals allocation in the admin portal. There is no CLI surface for Test Heals — UI inspection is required.
+
+- **Heals exist at the org level but not allocated to this tenant (step 6, or App Insights shows `Could not find any enabled consumption pools`):** allocate Heals to the specific tenant in the admin portal (Admin → Licenses → Consumables). Confirm the pool is in the **Enabled** state, not just present.
+
+- **License configuration looks correct but HA still produces empty data and the log line is absent:** the consumption pool may not be enabled on the tenant. Verify in the admin portal (Admin → Licenses → Consumables). There is no `uip` command for this — UI verification is required.
+
+- **Job "worked before" and started failing after upgrade:** likely UIA 24.10.x preview → 25.10.x GA, or 25.10.22 → 25.10.23+ where Test-runtime jobs now correctly demand Test Heals. Identify which threshold was crossed (step 4) and resolve via the matching branch above — do not roll back package versions as a permanent fix; preview HA is no longer supported.
+
+- **In all branches:** after the licensing issue is resolved, restart the same job (or trigger a new run). If HA produces data on the retry, the investigation continues with the recovery-data playbooks (`selector-failure-healing-fix.md` or `selector-failure-manual.md`). If HA still produces no data after the license fix, escalate to `no-recovery-data.md` (other causes: connectivity to Semantic Proxy / LLM Gateway, classic activity, image-only target).
+
+## References
+
+- Healing Agent prerequisites: https://docs.uipath.com/agents/automation-suite/2.2510/user-guide-ha/healing-agent-prerequisites
+- Healing Agent licensing (Flex): https://docs.uipath.com/agents/automation-cloud/latest/user-guide-ha/licensing#flex
+- Enabling Healing Agent for Test: https://docs.uipath.com/test-manager/automation-cloud/latest/user-guide/enabling-healing-agent
+- Test Cloud licensing: https://docs.uipath.com/test-cloud/automation-cloud/latest/admin-guide/licensing-test-cloud

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/playbooks/no-recovery-data.md

@@ -0,0 +1,35 @@
+---
+confidence: low
+---
+
+# Healing Agent — No Recovery Data
+
+## Context
+
+Healing Agent is enabled but no recovery data was generated after a UI automation failure.
+
+What this looks like:
+- Job faulted with a UI automation exception
+- AutopilotForRobots shows Enabled: true, HealingEnabled: true
+- But `healing-fixes.json` is empty or doesn't exist
+- No files in `healing-agent/uia/` directory
+
+What to look for:
+- Confirm HA is enabled by checking both `AutopilotForRobots.Enabled` and `AutopilotForRobots.HealingEnabled` (both must be true)
+- Do NOT rely on the legacy `EnableAutopilotHealing` field — it can be false even when HA is properly enabled
+- Check if the failure activity type is UIAutomation (HA only works with UI activities)
+
+What can cause it:
+- The activity uses classic UI automation (`UiPath.UIAutomation.*`) — HA may have limited support for classic activities depending on version
+- The failure happened before HA could capture the UI tree (application crashed, window closed)
+- The robot machine lost connectivity to Semantic Proxy / LLM Gateway during recovery attempt
+- HA analysis timed out — the UI tree was too complex or the LLM response was too slow
+- The activity uses image-based targeting which HA doesn't support for recovery
+- The robot does not have the required permissions to upload the files
+
+## Resolution
+
+- Verify the activity uses modern UI activities (`UiPath.UIAutomationNext.*`) for full HA support
+- Check Semantic Proxy and LLM Gateway health on the deployment
+- Check robot machine connectivity to cloud services and has the correct permissions
+- If HA consistently fails to produce data, escalate to platform team with the job ID and robot logs

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/playbooks/scope-container-wrong-page.md

@@ -0,0 +1,44 @@
+---
+confidence: medium
+---
+
+# Selector Failure — Scope Container Attached to Wrong Page/Window
+
+## Context
+
+A UI Automation activity faulted with a selector-not-found exception (`NodeNotFoundException`, `SelectorNotFoundException`, `UiElementNotFoundException`) but the inner selector itself is correct for its intended page. The actual defect is in the **enclosing scope container** — `NApplicationCard`, `NBrowser`, `Use Application/Browser`, `NWindow`, `Attach Browser`, `Attach Window` — which attached to a different application instance, browser tab, or page than the inner selector targets.
+
+What this looks like:
+- The inner selector is structurally sound and would resolve on the intended page.
+- The runtime "closest matches" in the exception belong to a completely different page, locale, or site than the inner selector expects.
+- The scope container has a permissive attach configuration that allows reuse of an unintended existing window/tab.
+
+What can cause it:
+- `AttachMode=ByInstance` + default `OpenMode=IfNotOpen`: the container reuses any existing window of the configured app instead of opening the intended URL.
+- `TargetApp.Selector` is permissive (e.g., `<html app='msedge.exe' title='Google' />` matches google.com, google.ro, google.de — any tab whose title contains "Google").
+- `TargetApp.Url` points at a homepage or generic landing page, but the inner selector targets a deeper route that requires navigation.
+- No `Navigate Browser` / `Go To URL` activity between scope attach and the inner selector to drive the attached browser to the right page.
+
+## Investigation
+
+1. Locate the faulted activity in the workflow source by `IdRef`, then walk up to its **enclosing scope container**.
+2. Read these scope-container attributes from the XAML:
+   - `AttachMode` (`ByProcessName`, `ByInstance`, `SingleWindow`)
+   - `OpenMode` (`IfNotOpen`, `Always`, `Never`). Absent = `IfNotOpen` default.
+   - `TargetApp.Selector` — the window/tab the container attempts to attach to.
+   - `TargetApp.Url` (browsers) — the URL the container opens when it does open the app.
+3. Compare against the inner activity's intended target:
+   - If the inner selector's `BrowserURL` / page-scoped attribute names a deeper route than `TargetApp.Url`, the scope cannot reach the inner target without explicit navigation.
+   - If `TargetApp.Selector` is loose (matches multiple tabs/pages) and `OpenMode=IfNotOpen`, the container will reuse whichever matching tab is already open — typically not the one the developer intended.
+4. Cross-check the runtime exception's `closest matches`: if they belong to a different page than the inner selector expects, the scope landed on the wrong page.
+
+## Resolution
+
+Fix the scope container, not the inner selector. Choose ONE:
+
+- **Force the container to navigate to the intended page on every run** — set the scope's `OpenMode=Always` (Studio: "Open in browser: Always") and set `TargetApp.Url` to the inner selector's intended page URL. The container always lands on the right page; the inner selector resolves.
+- **Tighten the scope's window/tab match** — replace `TargetApp.Selector` with a selector specific to the intended page (e.g., `title='Doodles - Google'` instead of `title='Google'`), keeping `OpenMode=IfNotOpen`. The container only reuses the correct tab.
+- **Insert a `Navigate Browser` / `Go To URL` activity before the inner selector** — keep the current scope, but explicitly drive the attached browser to the intended page before the click/extract. Use when the same scope must service multiple pages in sequence.
+- **Re-record the inner selector against the page the scope actually attaches to** — only when the design intent is to operate on the page the container lands on and the original selector was authored against the wrong page.
+
+Do NOT "fix" the inner selector (adding wildcards, switching to `automationId`, etc.) when the scope is the actual defect. Selector hardening masks the misconfig and leaves the same trap for future activities inside the same scope.