@uipath/skills 1.195.0 → 1.196.0

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/playbooks/application-not-found.md

@@ -0,0 +1,84 @@
+---
+confidence: high
+---
+
+# Application Not Found — Target Application Could Not Be Located
+
+## Context
+
+`ApplicationNotFoundException` is thrown by `NApplicationCard` (the runtime activity behind `Use Application`, `Use Browser`, and the standalone Application Card) when the target application cannot be located **and** the scope's `OpenMode` is set to `Never`. The exception is scope-level, not element-level — it fires before any inner `NClick` / `NTypeInto` / `NHover` runs, so the inner activities never get a chance to throw selector-level errors.
+
+What this looks like:
+- `ApplicationNotFoundException` (default message: `Could not find target application.`) in the job's error logs, sometimes with a closest-match diagnostic appended
+- Stack frame originates inside `UiPath.UIAutomationNext.Activities.NApplicationCard` — `ProcessAppNotFoundAsync` → `GetAppNotFoundExceptionAsync`
+- The faulted activity in XAML is a `Use Application` / `Use Browser` / `NApplicationCard` (or its alias), not an element-level activity
+- The scope's `OpenMode` is `Never` in the XAML (`<NAppOpenMode>Never</NAppOpenMode>` or the matching `TargetApp` property)
+
+What can cause it:
+- App is closed and `OpenMode=Never` blocks the scope from launching it
+- App is running but the application selector no longer matches (title drift, language change, version bump)
+- App was running at job start but crashed or was closed between scopes
+- Process is alive but has no visible window (minimized to tray, background-only, on another desktop)
+- App is still launching (cold start) and the selector matches a splash screen window that disappears before the scope attaches
+
+What this is NOT:
+- If the app is missing AND `OpenMode != Never`, the scope throws `ApplicationOpenException` instead (launch was attempted and failed) — different playbook
+- If the selector finds a window that belongs to a different process, the scope throws `WrongTargetApplicationException` — different playbook
+- Element-level failures (`SelectorNotFoundException`, `UiElementNotFoundException`) inside the scope mean the scope attached fine — use the selector-failure playbooks
+
+## Investigation
+
+1. Locate the faulted activity in XAML — the `IdRef` in the exception's outer activity points at a `Use Application` / `Use Browser` / `NApplicationCard`, not at an inner element activity
+2. Read the scope's `TargetApp` selector (and `TargetApp.OpenMode`) from XAML. Confirm `OpenMode=Never` — this is the gating condition for the exception. If `OpenMode != Never`, you're investigating the wrong playbook
+3. Extract any closest-match diagnostic from the exception message — UIAutomationNext appends one via `GetSearchErrorMessageAsync` when `ShowClosestMatchesInSearchError` is on. It tells you which running window came closest to matching
+4. Capture the application selector verbatim from XAML (decode `&amp;` → `&`, `&lt;` → `<`, etc.)
+5. Check the job's environment context for the app's launch responsibility — does any earlier activity launch it (a previous scope with `OpenMode=Always`, an `NCheckAppState`, or an out-of-band launcher), or is the workflow assuming the app is already running?
+6. If the app launches asynchronously (cold start, splash screen, license check), check whether an `NCheckAppState` or `Wait For Application` precedes the failing scope
+7. Compare the closest-match diagnostic against the selector — if a window is reported with similar attributes, the selector has drifted (renaming, language, version). If no closest match, the app is genuinely absent
+
+## Resolution
+
+Walk the decision tree below. Each branch maps to a distinct fix; choose the first one whose evidence holds.
+
+### Branch A — Workflow assumed the app was running but `OpenMode=Never` blocks the launch
+
+Evidence: no earlier activity in the workflow launches the target app, the closest-match diagnostic reports no candidate window, and the job environment confirms the app was not pre-launched by an external trigger.
+
+Fix: change the scope's `OpenMode` to `IfNotOpen` (preferred — only launches when needed) or `Always`, and set `FileName` / `Arguments` so the scope can launch the app itself. This is the most common root cause.
+
+### Branch B — Selector drift on a running app (title / version / language)
+
+Evidence: closest-match diagnostic reports a window from the expected process with similar but not identical attributes — title contains a new version string, the language changed, a sub-feature renamed the main window.
+
+Fix: relax the application selector — use wildcards for volatile parts (`title='Invoice Portal*'`), prefer stable attributes (`app`, `automationid`, `cls`) over `title`, or migrate the scope to an Object Repository application target so the selector is centrally maintained.
+
+### Branch C — App crashed mid-flow
+
+Evidence: a previous scope or activity in the same job successfully interacted with the same app (look for earlier `NClick` / `NTypeInto` / `NCheckAppState` against the same selector). The app died between scopes.
+
+Fix: add an `NCheckAppState` (Element Exists / App State) before the failing scope to detect that the app is gone, plus retry logic or a guarded re-launch. Investigate the crash separately — repeated `ApplicationNotFoundException` after this branch indicates an underlying app stability problem, not a workflow problem.
+
+### Branch D — Process exists but no visible window
+
+Evidence: the closest-match diagnostic returns nothing matching the selector, but the host process is known to be running (operator confirmation, prior log entries, telemetry). Common with apps minimized to system tray, second-monitor windows on an unattended robot, or background-only services.
+
+Fix: ensure the app's main window is visible before the scope — call an OS-level activity to restore from tray, switch desktops, or pin the window. If the workflow is unattended, configure the app launcher to start visible (not minimized).
+
+### Branch E — Cold-start race against a splash window
+
+Evidence: the failure is intermittent and clusters with first-job-after-machine-restart runs. The closest-match diagnostic reports a window with `app='loader.exe'` or similar that doesn't match the main app's selector.
+
+Fix: precede the scope with `NCheckAppState` waiting for the main-window selector (not the splash), or set the scope's `WaitForReady` to `Complete`. If the app's splash regularly outlives the scope's default timeout, raise the scope timeout.
+
+## Post-presentation actions
+
+This resolution path is **interactive** — every recommended fix above ends in a file edit (XAML property change, adding a new activity before the scope, adjusting timeouts). The orchestrator MUST call `AskUserQuestion` at the end of the troubleshooting to (a) print the exact property/file/line to be modified and the before → after value, and (b) ask the user whether to apply the fix. Do not write to the user's source files until that question is answered with explicit approval.
+
+Rules the agent MUST follow:
+
+1. **Sharing a file path is not approval.** If you previously asked the user for the project source location (e.g., "point me at the failing project") and they responded with a path, that consent covers reading the source only — not editing it. Issue a separate `AskUserQuestion` before any edit.
+2. **Never bundle "gather input" with "apply fix" in a single option.** Any option that contains phrasing like "I'll … apply / edit / write the change" alongside an input request must be split into two steps: gather the input, then surface the specific diff and confirm separately.
+3. **Surface the diff before asking.** The apply-fix question must include the file path, the activity `IdRef` or line number, the current value, and the proposed value. Vague approvals ("fix the scope") are not enough — show the concrete edit.
+4. **One question per fix, not one for the whole branch.** If multiple files need editing (e.g., XAML plus an Object Repository `.content` file mirror), list every file in the question or ask file-by-file. Do not silently propagate the same substitution to side-channel files.
+5. The presenter must emit a `## Post-presentation actions` block in its output declaring this interactive step; the orchestrator must execute it before closing the investigation. Do not collapse this into a generic "fix the OpenMode" recommendation — the apply-fix prompt is part of the documented resolution.
+6. **If you cannot obtain interactive approval, do not edit.** When the approval prompt is unavailable or errors in the current environment, fall back to presenting the diff as a recommendation and stop — leave the apply step to the user. Never write to a source file without explicit approval, even when the approval mechanism is unavailable. A recommendation-only close is always acceptable; a silent edit is not.

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/playbooks/application-open-failed.md

@@ -0,0 +1,46 @@
+---
+confidence: high
+---
+
+# Application Could Not Open — Launch Attempted and Failed
+
+## Context
+
+A `Use Application/Browser` scope (the `NApplicationCard` activity) was configured to **open** the target application — `Open` is `IfNotOpen` or `Always` (anything other than `Never`) — and the launch attempt failed. The scope throws `ApplicationOpenException` before any inner `NClick` / `NTypeInto` / `NGetText` runs, so the inner activities never execute.
+
+What this looks like:
+- Exception class: `ApplicationOpenException`
+- Friendly message: `Could not open target application.`
+- The faulted activity is the `Use Application` / `Use Browser` / Application Card scope, not an inner element activity.
+- The scope's `Open` mode is `IfNotOpen` or `Always` (NOT `Never`) — the scope tried to start the app itself.
+
+What can cause it:
+- The `File path` / `Arguments` point at an executable that is missing, moved, or not installed on the robot machine.
+- The application started but its window never appeared within the scope timeout (slow cold start, splash screen, license/activation dialog that blocks startup).
+- A login, consent, or "another instance is running" dialog intercepts the launch.
+- For browsers: the browser is not installed, or the WebDriver/browser extension required by the chosen browser type could not be initialized.
+- The robot lacks the rights to launch the process (elevation required, blocked by policy).
+
+What to look for:
+- Confirm the exception is `ApplicationOpenException`, not `ApplicationNotFound` (that one is the `Open = Never` case — the scope was told not to launch; use the application-not-found playbook) and not `WrongTargetApplicationException` (the scope reached a different app — see wrong-target-application).
+- Read the scope's `File path`, `Arguments`, and `Open` mode from the workflow source.
+- Check the robot/environment: is the executable present at that path on the machine that ran the job? Was the app already mid-launch?
+
+## Investigation
+
+1. From the failed job, capture the exception class, message, and the scope activity's name and workflow file.
+2. Open the workflow and read the scope's `Target application` settings: `File path`, `Arguments`, `Open` mode, and the application/window selector.
+3. Verify the `File path` resolves on the robot machine (correct install location, drive, and bitness). A path that exists on the developer machine but not the robot is the most common cause.
+4. Check whether the launch is blocked: look for a login/activation/consent dialog the app shows on first start, or a "running as a different user / elevation" requirement.
+5. For a browser scope: confirm the browser is installed and the browser type matches; confirm the browser extension / WebDriver could initialize.
+6. Check timing: if the app cold-starts slowly, the window may not be ready before the scope timeout expires.
+
+## Resolution
+
+- **File path wrong/missing on the robot:** correct `File path` (and `Arguments`) to the install location present on the robot, or deploy the application to the robot. Prefer an environment-agnostic path over a hard-coded developer path.
+- **Launch blocked by a startup dialog:** the dialog is the originating fault — handle it deterministically (dismiss/sign in before the scope, or configure the app to skip it), rather than retrying the open blindly.
+- **Permissions/elevation:** run the robot with the rights the app needs, or configure the app to start without elevation.
+- **Browser not installed / WebDriver issue:** install the matching browser, align the browser type, and ensure the required extension/WebDriver is available on the robot.
+- **Slow cold start:** raise the scope timeout to cover the app's genuine startup time. Do not raise it blindly — confirm the app does eventually open.
+
+Do not switch `Open` to `Never` to avoid the launch — that only converts this into an `ApplicationNotFound` when the app is absent. Fix the launch itself.

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/playbooks/browser-navigation-failed.md

@@ -0,0 +1,45 @@
+---
+confidence: medium
+---
+
+# Go To URL — Navigation Failed
+
+## Context
+
+A `Go To URL` activity (`NGoToUrl`) could not navigate the attached browser to the requested address. The browser context was reached, but the navigation itself failed or the URL was not usable.
+
+What this looks like:
+- One of these signatures during a `Go To URL`:
+  - `Required argument 'URL' was not provided.` — the `Url` input was empty/whitespace at runtime.
+  - `Requested URL is invalid, value is null.` (`BrowserInvalidURLException`)
+  - `Failed to navigate to the specified URL.` (`BrowserFailedToNavigateToUrlException`)
+  - For a local file address on a Chromium browser: `Failed to open the indicated local URL.\nPlease go to "Extensions" and enable "Allow access to file URLs".`
+
+What can cause it:
+- The `Url` value is empty at runtime — typically a variable/expression that an earlier step was supposed to populate but didn't.
+- The URL is malformed (missing scheme, stray characters).
+- The site/host is unreachable from the robot (network, DNS, proxy, certificate).
+- No browser is attached — `Go To URL` runs outside a live `Use Browser` context.
+- A local `file://` URL is used with a Chromium browser whose extension does not have "Allow access to file URLs" enabled.
+
+What to look for:
+- Confirm the faulting activity is `Go To URL`.
+- Read where the `Url` value comes from (literal vs variable) and what it evaluates to.
+- Check whether a `Use Browser` scope is active around the activity.
+
+## Investigation
+
+1. From the failed job, capture which of the messages above appeared and the `Go To URL` activity + workflow.
+2. Read the `Url` input. If it is a variable/expression, trace the upstream step that should produce it; an empty value means that step did not run or returned nothing.
+3. If the URL is present, validate its format (scheme + host).
+4. Confirm a `Use Browser` scope encloses the activity and was attached at this point.
+5. For navigation failures on a present, well-formed URL: check robot-side reachability (network/proxy/cert) to that host.
+6. For a `file://` URL on Chromium: check the "Allow access to file URLs" extension permission.
+
+## Resolution
+
+- **Empty `Url`:** fix the upstream step that should produce the value — do not hard-code a literal to paper over a missing producer unless the URL is genuinely static.
+- **Malformed URL:** correct the address (include the scheme).
+- **Site unreachable:** resolve the robot-side connectivity/proxy/certificate issue to that host.
+- **No browser attached:** ensure `Go To URL` runs inside a live `Use Browser` scope.
+- **Local file URL on Chromium:** enable "Allow access to file URLs" for the automation extension on that browser.

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/playbooks/click-coordinate-off-screen.md

@@ -0,0 +1,120 @@
+---
+confidence: high
+---
+
+# Click Coordinate Off-Screen — HardwareEvents
+
+## Context
+
+A UI Automation input activity (`NClick`, `NTypeInto`, `NHover`, or any descendant of `Activities.Workflow.Input.*`) faulted at the cursor-injection stage because the destination coordinate fell outside the runtime host's virtual-screen rectangle. The element was located successfully by selector; the OS rejected the absolute coordinate before any input was sent. This is **not** a selector-resolution failure — do not match against `selector-failure-*` playbooks.
+
+What this looks like:
+
+- Exception type: `UiPath.UIAutomationNext.Exceptions.UiAutomationException`
+- Exception message: literally `"Cannot send input to UI element because it is outside of screen bounds."`
+- Inner exception: `System.Runtime.InteropServices.COMException`, HRESULT `0x800402bd`
+- Stack frame origin: `UiPath.UiNodeClass.Click` → `UiInputService.ClickAtPointAsync` → `UiInputService.ClickAsync` (the element was already located before the throw)
+- Job runs only a few seconds before faulting — the failure is at first input, not after waiting for an element
+
+What can cause it — four distinct mechanisms, each fits a different XAML pattern:
+
+- **C1. Page-scroll mismatch (web targets only).** The page was scrolled at design time so the element was visible in the viewport; at runtime the page loads at scroll=0 and the element sits below the fold. The selector still resolves (DOM is unchanged) but the element's runtime screen Y is huge. Typical fingerprint: `NBrowser` / `NApplicationCard` (browser scope) AND no `Scroll`, `Scroll Into View`, `Hover`, or anchor-bearing `Navigate Browser` activity precedes the input. `Target.DesignTimeRectangle` and `TargetApp.Area` look fine in isolation — the geometry math against the host doesn't expose the cause.
+- **C2. Window not normalized at runtime.** `AttachMode=ByInstance` reuses whatever window state the application already has — minimized, half-height, positioned off the visible monitor. The runtime viewport ends up smaller or differently positioned than the design-time canvas. Typical fingerprint: `AttachMode=ByInstance` AND no `Maximize Window` / `Set Browser Size` / `Set Window State` / `Move Window` precedes the input.
+- **C3. Multi-monitor design canvas → single-monitor host.** The element's natural DOM/layout position genuinely doesn't fit any window the host can provide. Even maximized to the host's full virtual screen, the element renders past the host's MaxY (or MaxX). Typical fingerprint: `TargetApp.Area` extends past the runtime host's virtual-screen rectangle (e.g., `Area = -13, -13, 3866, 2330` on a single 1920×1080 host).
+- **C4. Sticky chrome displacement.** A header, cookie banner, popup, modal, browser update notification, or Windows taskbar accumulated at runtime and pushed the element below the visible viewport even though the page is at the right scroll position and the window is correctly sized.
+
+> **C1 vs C2 are indistinguishable from XAML alone.** A `ByInstance` browser scope with no preceding sizing AND no preceding scroll fits both. When both step 5b and step 5c fire, accept the ambiguity, recommend the universal fix, and present — do not loop trying to pick one. Asking the user "was the window maximized?" / "was the page scrolled?" almost always gets "I don't know" — accept that and present.
+
+`InteractionMode=HardwareEvents` (or `WindowMessages`) is the necessary precondition for **all four** mechanisms — those modes drive the real OS cursor at an absolute screen coordinate. The viewport-independent modes (`DebuggerApi`, `Simulate`, or `SameAsCard` when the enclosing scope uses one of those) operate on the application's DOM / accessibility tree and bypass the screen-coordinate requirement entirely.
+
+> **Valid `InteractionMode` values for input activities in UIAutomationNext:** `SameAsCard`, `HardwareEvents`, `Simulate`, `DebuggerApi`, `WindowMessages`. Do NOT recommend or write any value outside this list — XAML deserialization will fail on unknown values (the activity won't load in Studio or at runtime). In particular, `ChromiumAPI` is **not** a valid value in this enum; recommend `DebuggerApi` instead for Chromium browser scopes.
+
+## Investigation
+
+1. **Confirm the exception signature.** Read the job's error log via `uip or jobs logs <job-key> --level Error --output json`. The combination of exception class `UiAutomationException`, message containing "outside of screen bounds", and inner `COMException` `0x800402bd` is definitive — no other playbook in this folder matches this signature, do not branch to `selector-failure-*`.
+
+2. **Identify the faulted activity and its scope container.** From the job's traces (`uip or traces spans get --job-key <job-key> --output json`) and/or workflow source, locate the input activity by `IdRef` and walk up to its enclosing scope container (`NApplicationCard`, `NBrowser`, `Use Application/Browser`, `NWindow`).
+
+3. **Extract the geometry signals from the XAML.** From the input activity element:
+   - `InteractionMode` — confirm it is `HardwareEvents` (or `WindowMessages`). If it is `DebuggerApi`, `Simulate`, or `SameAsCard` chained to a non-OS-cursor mode, this playbook does not apply (those modes don't dispatch OS cursor input).
+   - `Target.DesignTimeRectangle` (format: `X, Y, Width, Height`) — the captured rectangle of the resolved element. Treat as a hint, **not** the runtime click target.
+   - `HealingAgentBehavior` on the activity, and on the scope container.
+
+   From the enclosing scope container:
+   - `TargetApp.Area` (format: `X, Y, Width, Height`) — the design-time canvas. Compute `MaxX = X + Width`, `MaxY = Y + Height`.
+   - `TargetApp.Selector` / `TargetApp.Url` — used to decide whether the target is web (C1 candidate) or desktop.
+   - `AttachMode` (`ByInstance` / `SingleWindow` / `ByProcessName`).
+
+4. **Walk preceding siblings of the input activity inside the scope body.** Record presence/absence of each of these in order:
+   - Scroll-class activities — `Scroll`, `Scroll Into View`, `Hover` targeting the failing element, or `Navigate Browser` / `Go To URL` with an in-page anchor (`#fragment`). Absence is the C1 fingerprint.
+   - Sizing-class activities — `Maximize Window`, `Set Window State`, `Set Browser Size`, `Move Window`, `Restore Window`. Absence (combined with `AttachMode=ByInstance`) is the C2 fingerprint.
+   - Project-wide grep these too — gaps that are structural across the codebase (no sizing activity in ANY workflow) are stronger evidence than a local omission.
+
+5. **Pick the sub-cause via this decision tree.** Apply in order; stop at the first match:
+
+   ```
+   5a. Is the target a browser (TargetApp.Url is set, BrowserType is Edge/Chrome/Firefox,
+       or scope is NBrowser)?
+
+       YES → 5b.
+       NO  → skip to 5c.
+
+   5b. Preceding-scroll check (web targets):
+       - No Scroll / Scroll Into View / Hover / anchor-navigation activity before the
+         input AND the failing element is likely below the fold on a fresh page-load
+         (deep in the document, common for "Learn More", "Footer", "Submit" controls
+         on long pages) → C1 (page-scroll mismatch). This is the most common web case.
+       - A preceding scroll exists but the element is still off-screen → proceed to 5c
+         (window-state or chrome).
+
+   5c. Window-state check:
+       - AttachMode=ByInstance AND no preceding Maximize Window / Set Browser Size /
+         Set Window State / Move Window → C2 (window not normalized).
+       - Otherwise → 5d.
+
+   5d. Geometry check:
+       - From job-get, read HostMachineName. The runtime virtual-screen rectangle of
+         that host is the failure boundary. Compare element-center (X+W/2, Y+H/2)
+         from DesignTimeRectangle against the host rectangle.
+       - Element-center fits inside host's screen → C3 ELIMINATED. The element would
+         render on-screen if the window were maximized and the page were scrolled —
+         loop back to 5b/5c.
+       - Element-center exceeds host's screen even when fully maximized → C3 confirmed
+         (multi-monitor design → smaller host).
+
+   5e. Chrome / overlay check:
+       - User reports a banner, popup, modal, cookie prompt, or browser-update overlay
+         appearing on the affected page → C4 (sticky chrome).
+       - Otherwise the cause is undetermined — recommend the universal fix from
+         Resolution and surface the ambiguity to the user.
+   ```
+
+   **Host-geometry data.** Do NOT fabricate or assume the host's display geometry. The `uip` CLI does not currently expose monitor/resolution metadata for a robot host (`or machines list` returns registration metadata only — no `Resolution`, `VirtualScreenRectangle`, or `Monitors` fields). If you cannot derive the runtime virtual-screen rectangle from a verified source (job logs, traces, an attached screenshot, a Healing-Agent capture), STOP and write `.local/investigations/needs_input.json` per `agents/shared.md` § "Requesting User Input". Ask for the host's display configuration with concrete option ranges (e.g., `1920x1080`, `2560x1440`, `3840x2160`, `multi-monitor with primary <X>x<Y>`). Do NOT default to any "typical" value — choosing the wrong sub-cause picks the wrong fix.
+
+   **When the orchestrator re-spawns you with the user's answer**, continue from this step: re-run the decision tree using the new data and pick the matching sub-cause. Do NOT stop at "answer received" — the answer is an input to *complete* your verdict, not the verdict itself. Record the diff in your evidence file and set the hypothesis status before returning to the orchestrator.
+
+6. **Confirm Healing could not relocate.** Read job-get → `JobInputArguments` / process settings for `AutopilotForRobots.HealingEnabled`. Confirm the job-error log contains `Healing agent is disabled for the current job.` or the equivalent. If Healing was enabled but produced no fix, switch to `no-recovery-data.md`.
+
+## Causes
+
+Name the confirmed sub-cause exactly:
+
+- **C1.** Page-scroll mismatch — design-time captured the element at a scrolled viewport position; runtime opens at scroll=0; the element sits below the fold. Web targets only.
+- **C2.** Window not normalized at runtime — `AttachMode=ByInstance` inherits whatever window state the application already has, and no preceding activity sizes/positions it before the click.
+- **C3.** Multi-monitor design canvas → smaller host — the element's natural layout position exceeds the host's virtual screen even with the window maximized.
+- **C4.** Sticky chrome — header/banner/modal/popup displaced the element below the viewport.
+
+Do NOT assert a sub-cause unless step 5's decision tree actually arrived at it.
+
+## Resolution
+
+Pick the fix that matches the identified sub-cause. The interaction-mode switch is the **universal fix** — it covers all four sub-causes and is the safest recommendation when the cause is ambiguous.
+
+- **Universal fix — switch the interaction mode** (covers C1, C2, C3, C4). Change the activity's `InteractionMode` to a viewport-independent value from the **valid enum**: `SameAsCard`, `HardwareEvents`, `Simulate`, `DebuggerApi`, `WindowMessages`. For a browser scope, recommend `DebuggerApi` (drives input through the Chromium debugger / DOM); for a desktop application, recommend `Simulate` (drives input through the UI accessibility tree). If the enclosing `NApplicationCard` / `NBrowser` already runs `InteractionMode=DebuggerApi` or `Simulate`, recommend `SameAsCard` so the activity inherits that mode without re-stating it. These modes do not require an on-screen coordinate. **Never recommend `ChromiumAPI` — it is not a valid enum value and XAML deserialization will fail on it.** Recommended unless `HardwareEvents` is mandatory (e.g., the target application doesn't expose a scripting surface and only accepts real input events).
+- **C1-specific fix — scroll the element into view.** Insert a `Scroll Into View` activity targeting the failing element as the first child of the scope's body (or immediately before the input). For pages with a static anchor, `Navigate Browser` with the `#fragment` URL also works. Use when staying on `HardwareEvents` is required and the cause is the page-scroll mismatch.
+- **C2-specific fix — normalize the application window.** Insert a `Maximize Window`, `Set Window State`, or `Set Browser Size` activity before the input. Use when the cause is window-state inheritance and the workflow must remain on `HardwareEvents`.
+- **C3-specific fix — re-capture on a single-monitor canvas.** Re-record the scope container and the input activity on a display configuration matching production. The new `TargetApp.Area` and `DesignTimeRectangle` will fit the runtime host. Use when the project was authored on a wider canvas than production hosts can ever provide.
+- **C4-specific fix — dismiss the chrome.** Insert an activity to close the banner / popup / modal before the input (`Click` on the close button, `Send Hotkey Esc`, or a CSS-rule injection through a script step).
+- **Enable Healing Agent on the process** — set `AutopilotForRobots.HealingEnabled=true` in the release's `ProcessSettings`. Healing can relocate an off-screen coordinate on retry. Use as defense-in-depth; it does not fix the underlying authoring gap.
+
+Do NOT "fix" the selector (adding wildcards, switching to `automationId`, tightening attributes). The selector resolved correctly — selector hardening is wrong for this fault class and masks the real defect.

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

@@ -21,8 +21,6 @@ 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).
 

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/playbooks/element-found-not-actionable.md

@@ -0,0 +1,43 @@
+---
+confidence: medium
+---
+
+# Element Found But Not Actionable — Stale, Not Visible, or Blocked
+
+## Context
+
+The selector resolved (or the search reached the right place), but the activity could not act on the element: it went invalid between find and action, it is not visible, or a dialog is blocking access to it. This is distinct from a genuine selector mismatch and from a disabled element.
+
+What this looks like — one of these signatures:
+- `The UI element is invalid. Make sure the target application is open and the element is on the screen.` (`InvalidNodeException`)
+- `The selected UI element seems to have become invalid. Please make sure the UI element is still on the screen.` (`UiNodeUninitializedElementException`)
+- `Cannot get the screen rectangle of this UI node. A possible reason might be that the element is not visible.` — the element exists but has no usable on-screen rectangle (minimized, collapsed, scrolled out, zero-size).
+- `The element was found but its visibility was not as expected (Visible). ...` (`TargetFoundButNotVisibleException`) — the target's configured visibility didn't match at runtime.
+- `The element was not found, and it might be due to the dialog blocking the browser.` (`TargetNotFoundBrowserBlockedException`) — a modal/JS dialog blocked the browser, so the element couldn't be reached.
+
+What can cause it:
+- The window closed, navigated, or re-rendered between locating the element and acting on it (the element handle went stale). Usually an upstream step left the page changing under the activity, or a timing gap.
+- The element is present but hidden/collapsed/scrolled away, so it has no actionable rectangle.
+- The target was authored expecting a different visibility state than it has at runtime.
+- A browser dialog (alert/confirm/print/auth) is up, freezing the page so the element cannot be located or acted on.
+
+What to look for:
+- Confirm the exception is one of the above — the element was located/expected, so this is NOT a plain `selector-failure-*` (genuine not-found) and NOT `disabled-element` (target found but disabled).
+- The "outside of screen bounds" coordinate-injection failure on Hardware Events is a different signature, covered by its own dedicated playbook — not this one.
+- Check whether the page/window was changing, hidden, or had a dialog open at action time.
+
+## Investigation
+
+1. From the failed job, capture the exact message and the faulting activity + workflow.
+2. Determine which state applies: stale (invalid/uninitialized), not-visible (no rectangle / visibility mismatch), or browser-blocked (dialog).
+3. For stale elements, look at what runs just before: an upstream click/navigation that keeps the page reloading, or a too-short gap before the action.
+4. For not-visible, check whether the element is hidden until a prior step reveals it (expand/scroll/tab switch) and whether the target's expected visibility matches reality.
+5. For browser-blocked, check whether a JavaScript dialog or native browser prompt appears around that step.
+
+## Resolution
+
+- **Stale (invalid/uninitialized):** the element changed under the activity. Re-establish the element right before acting — add a `Check App State` (Element Exists) gate so the action runs only once the element is present and stable; and trace the upstream step that keeps the page changing and fix that.
+- **Not visible / no rectangle:** make the element actually visible before acting — bring it into view via the legitimate flow (expand the section, switch the tab, scroll), or correct the target's expected visibility if it was authored wrong. Do not work around it by acting on a hidden element.
+- **Browser blocked by a dialog:** the dialog is the originating fault. Handle it deterministically — dismiss/accept the dialog as a real step in the flow (or prevent it) before the activity. 
+
+Do not harden the selector (wildcards, switching attributes) for this class — the element was found/expected; selector changes don't address staleness, visibility, or a blocking dialog.

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

@@ -15,14 +15,14 @@ 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 |
+| **ProcessType of the release** | `TestAutomationProcess` (case-insensitive) → **Test Heals** required. Any other value — `Process`, empty, or absent → regular **Heals** required. | Sole discriminator. HA reads `ProcessType` off the job; `RuntimeType` does **not** factor in — an `AppTest`/`TestAutomation` runtime whose release is not a Test Automation project still requests regular Heals. |
 
 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`).
+- The operation code in the log line distinguishes the pool: **`HealingAgent.Test`** = Test Heals requested (release `ProcessType = TestAutomationProcess`), **`HealingAgent`** = regular Heals requested (any other `ProcessType`). 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)
 
@@ -36,8 +36,8 @@ Consumption rates after the bundled 5K heals are exhausted: **3 Platform Units p
 ### 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.
+2. **Heals/Test Heals pool mismatch.** The release is a Test Automation project (`ProcessType = TestAutomationProcess`, e.g. published from Test Manager / run via Test Cloud) so HA requests Test Heals, but the tenant only has regular Heals allocated. Even with thousands of regular Heals and bundled trial Heals, a Test Automation project with 0 Test Heals will fail. The robot's runtime (Attended/Unattended) does not change this — the pool follows `ProcessType`, not the robot. **Flex tenants cannot assign Test Heals at all** — only Unified can.
+3. **UIA package version behavior.** **UIA 25.10.22 and lower always consumes regular Heals regardless of job type** — it does not differentiate. **UIA 25.10.23 and above** differentiates: a release published as a Test Automation project (`ProcessType = TestAutomationProcess`) consumes Test Heals. This means a Flex tenant whose Test Automation project healed fine on UIA 25.10.22 (consumed Heals) fails after upgrading to 25.10.23+, because Test Heals are now required and Flex cannot assign them.
 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.
@@ -47,19 +47,19 @@ Consumption rates after the bundled 5K heals are exhausted: **3 Platform Units p
 
 - **`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.
+- 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 release `ProcessType` (not the robot type or RuntimeType) determines 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.Test` → Test Heals were requested. The release is a Test Automation project (`ProcessType = TestAutomationProcess`). 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.
+   - `ProcessType` — the sole pool discriminator. `TestAutomationProcess` (case-insensitive) → HA requests Test Heals; any other value (`Process`, empty, absent) → regular Heals. `RuntimeType` is also returned but does **not** affect the pool — ignore it for licensing.
    - `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.
@@ -68,8 +68,8 @@ Consumption rates after the bundled 5K heals are exhausted: **3 Platform Units p
 
 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.
+   - **25.10.22 and below** → does not differentiate Heals vs Test Heals (always consumes regular Heals). Symptom: a Test Automation project 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+** → selects the pool by `ProcessType` (`TestAutomationProcess` → Test Heals).
 
 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.
@@ -89,15 +89,15 @@ Pick the branch that matches the operation code from step 1 and the `licenses in
 
 - **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:
+- **Operation code `HealingAgent.Test` (release `ProcessType = TestAutomationProcess`):** 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.
+  - **Flex tenant:** Flex **cannot** assign Test Heals. Options: (a) migrate to Unified to access Test Heals, (b) run the workflow as a regular automation process (not a Test Automation project / not via Test Manager) so its `ProcessType` is not `TestAutomationProcess` and HA consumes regular Heals — this is a property of the release, not the robot, so switching robot runtime does not help, or (c) **temporarily pin UIA to 25.10.22 or lower** so the activity consumes regular Heals regardless of `ProcessType` (workaround only — 25.10.23+ requires Test Heals for Test Automation projects). 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.
+- **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 Automation projects now require 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).
 

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

@@ -0,0 +1,108 @@
+---
+confidence: high
+---
+
+# Healing Agent — Orchestrator Status, Logs & Notifications (Is This Expected?)
+
+## Context
+
+Customer sees a Healing Agent (HA) signal on an Orchestrator-side surface — a Jobs-grid status, a robot log line, an email/in-app notification, or an informational "no license" notice — and asks whether it is **expected** and whether HA is silently running or consuming units. Four distinct surfaces produce these reports. They look alike but mean different things. Route by **WHERE the customer saw it**.
+
+### Routing table — pick the surface first
+
+| # | Surface (where seen) | Tell-tale string | Default verdict |
+|---|----------------------|------------------|-----------------|
+| 1 | Jobs grid → **"Healing Agent" column**, or job detail → **"Healing Agent" tab** | `Issues Detected`; tab banner `Unlicensed version` (preview) | Expected. Detection-only; on preview UIA (`24.10.x`) detects unlicensed. No unit spend. |
+| 2 | Job detail → **Logs** tab, robot Info log | `Healing agent configuration.` / `Healing Agent settings` | Benign config read. Appears every run. Non-blocking, zero consumption. |
+| 3 | **Email / in-app "Notification Summary"**, Component = Healing Agent | `a problem has been identified… recommendations… available for review` | Real HA event → org is licensed OR on preview `24.10.x` (alerts unlicensed). |
+| 4 | Robot log, informational notice | `'<activity>' activity recovery failed. No available license / Agentic units to perform healing analysis and recovery.` | Benign if customer does NOT want HA (job continues). If they DO → real error. |
+
+If the surface does not match any row, this playbook does not apply.
+
+### Does this consume units? (shared rule — applies to all four surfaces)
+
+- **Prereqs not met** (wrong UIA version, or no UI activity in process) → HA never engages, the Healing Agent panel does not show, **zero consumption**.
+- **Prereqs met but no license/units** → HA logs "No license available", does nothing, **job runs normally, zero consumption**.
+- **Units charged only on a successful heal/recommendation.** Recommendation-only consumes the same as self-heal. HA can heal via **local heuristics with no LLM call** (e.g. org AI Trust Layer policy blocks AI), so detection shown ≠ LLM/unit spend.
+
+HA is **available by default — recommendations on, self-healing off** (docs: "Healing Agent is available by default, offering only fix recommendations, not self-healing"). A signal appearing on a process the customer never explicitly enabled is expected for that reason. Self-healing must be activated explicitly per process/job.
+
+---
+
+### Surface 1 — Jobs-grid `Issues Detected` / Healing Agent tab
+
+**What it means.** HA ran during the job and **flagged one or more UI automation issues** (analyzed the failure, may have generated recommendations). Detection/indicative status — does NOT by itself mean HA self-healed or that recommendations are actionable under the current license. On **preview UIA `24.10.x`** HA detects and analyzes **without any license check**, so the column populates even on a tenant with zero entitlement. The job's Healing Agent tab confirms with:
+
+> ⚠ **Unlicensed version** — A preview version of the Healing Agent is currently in use. To upgrade to the GA version, update to the GA release of the UIAutomation.Activities packages. **Remaining days: 0**
+
+That banner is the tell. GA UIA (`25.10.2`+) enforces licensing — without entitlement HA does not run, so the status reflects GA enforcement instead of preview detection. A single tenant can show both: robots pinned to preview `24.10.x` populate `Issues Detected` unlicensed; `25.10.2`+ robots do not. Identify the package version **per job**, not per tenant.
+
+> The Jobs-grid Healing Agent column **filter is over-inclusive** — it surfaces jobs where HA was flagged but did not actually engage. For true engagement, use **Insights** (Healing Agent templates), not the grid filter.
+
+**Investigation cue.** Identify the UIAutomation.Activities version for that specific job (read `project.json` if local). `24.10.x` → preview, detects unlicensed (primary branch). `25.10.2`+ → GA, requires entitlement → check `licenses info`.
+
+**Resolution.**
+- Preview `24.10.x` + no entitlement: **expected and informational**. No self-heal, no unit spend. To make HA actionable → upgrade to GA `25.10.2`+, acquire the Healing Agent add-on, allocate Heals/units. If they do NOT want HA → preview HA is deprecated: Enterprise tenants must upgrade to GA by **1 Nov 2025**, after which the preview **Healing Agent Orchestrator Jobs panel ceases to function and is disabled**. Upgrading to GA without the add-on means HA will not run and the status stops appearing. No setting fully suppresses preview detection on `24.10.x` short of upgrading.
+- GA `25.10.2`+ + entitlement present (`Allowed.AgentService > 0`): tenant **is** licensed (check for promo, bundled Heals, or active trial). `Issues Detected` is normal — to act on findings, see [selector-failure-healing-fix.md](./selector-failure-healing-fix.md) or [no-recovery-data.md](./no-recovery-data.md).
+
+### Surface 2 — Robot Info log `"Healing agent configuration."` / `"Healing Agent settings"`
+
+**What it means.** Benign config read. Appears on **every** run regardless of license or whether HA is enabled — the robot reads HA settings at startup. **Non-blocking, consumes nothing.** The visible timestamp gap before/after this line is an **async-logging artifact** — the workflow does NOT wait on this log; it is NOT HA gating execution. Newer UIA reworded the line to state the actual HA state, because the old wording caused exactly this confusion. There is no setting that suppresses this line short of upgrading UIA; disabling HA in libraries/Automation Ops does not remove it.
+
+**Investigation cue.** Confirm the line is `Level: Info` in the Logs tab and that the customer's concern is latency or "is HA running secretly". Pull logs: `uip or jobs logs <job-key> --output json`.
+
+**Resolution.** Tell the customer the line is informational config-read only — no execution wait, no consumption. Latency they observe between timestamps is a logging artifact, not an HA network round-trip blocking the run. If they want the clearer wording, upgrade UIA to a version that reports HA state.
+
+### Surface 3 — Orchestrator email / in-app "Notification Summary", Component = Healing Agent
+
+**What it means.** A **real HA event** — HA does not send a notification unless it actually did something, and to do something the org must have the correct license. So either the org **has an HA license/active trial**, OR it is on **preview UIA `24.10.x`**, which alerts unlicensed (same preview root cause as Surface 1). HA notifications fire on a Heals-usage / recommendation event, not on license status — a notification means HA produced something, not that licensing changed. The notification text reads: "a problem has been identified within the job. Recommendations for resolution or self-healing procedures have been quickly generated and are now available for review."
+
+**Investigation cue.** Identify the UIA version of the process that triggered the alert (`24.10.x` preview vs `25.10.2`+ GA). Check entitlement with `uip or licenses info --output json`. Recall HA is available by default (recommendations on) — the triggering process may have been auto-enabled without the customer realizing.
+
+**Resolution.**
+- Preview `24.10.x`: alerts fire unlicensed. Same fix as Surface 1 — upgrade to GA / provision add-on, or accept the alerts until the preview Jobs panel is disabled on 1 Nov 2025. No way to stop the alerts on `24.10.x` short of upgrading.
+- GA `25.10.2`+ with entitlement: the org **is** licensed (promo, bundled Heals, or trial) — the alert is a genuine HA recommendation event. Open the job's Healing Agent tab to review.
+- Customer worried about silent unit spend: see the shared consume block — a notification means HA produced a recommendation, which is a charged event only if a license was available; preview detection charges nothing.
+
+### Surface 4 — `'<activity>' activity recovery failed. No available license / Agentic units…` (informational)
+
+**What it means.** HA was enabled and prereqs were met, but the tenant lacks an available consumable pool, so HA logged this notice and did nothing. **The job continues normally.**
+
+**Investigation cue.** Determine intent: does the customer **want** HA working?
+
+**Resolution.**
+- Customer does **NOT** want HA: the notice is **benign/non-blocking** — the job ran fine, nothing consumed. Optionally disable HA on the process/Automation Ops to stop the notice.
+- Customer **DOES** want HA: this is the real licensing error → [healing-agent-no-license.md](./healing-agent-no-license.md).
+
+---
+
+## Investigation
+
+1. **Confirm the surface** against the routing table. Route by where the customer saw it. A status, a log line, a notification, and the no-license notice are four different things — do not conflate.
+2. **Identify the UIAutomation.Activities version per job.** Read `project.json` if local. `24.10.x` = preview (detects/alerts unlicensed). `25.10.2`+ = GA (enforces license).
+3. **Read the job's HA state.** `uip or jobs get <job-key> --output json` — check `AutopilotForRobots.Enabled` and `AutopilotForRobots.HealingEnabled`. Cross-folder; no `--folder-path` flag.
+4. **Pull logs when the surface is a log line or notification.** `uip or jobs logs <job-key> --output json` (add `--level Error` for Surface 4's notice). Cross-folder.
+5. **Fetch the recovery archive to confirm engagement.** `uip or jobs healing-data <job-key> -o <out>.zip` — a populated archive corroborates HA produced detection/recommendation data; a 22-byte ZIP is empty (HA produced nothing).
+6. **Check entitlement.** `uip or licenses info --output json`: `Data.Allowed.AgentService > 0` with HA features in `Data.LicensedFeatures` → tenant is entitled. `== 0` with `LicensedFeatures: []` → no entitlement. `SubscriptionPlan` is the tier label only and does NOT encode Flex vs Unified — never branch on it alone.
+
+## Resolution
+
+Apply the per-surface Resolution above for the matched row. Cross-cutting rules:
+
+- **Preview `24.10.x` is the common unlicensed cause for Surfaces 1 and 3.** Detection/alerts without entitlement are expected; nothing is consumed. Preview is deprecated: Enterprise tenants must upgrade to GA by 1 Nov 2025, after which the preview Orchestrator Jobs panel is disabled. Upgrade to GA `25.10.2`+ + provision the add-on to make HA actionable, or accept the signals until then.
+- **Surface 2** is always benign — config read, no consumption, no execution wait.
+- **Surface 4** routes on intent: benign if HA unwanted; otherwise → [healing-agent-no-license.md](./healing-agent-no-license.md).
+- Use **Insights** (Healing Agent templates) for the true engagement/consumption picture — the Jobs-grid filter over-reports.
+
+## Distinguish from related playbooks
+
+- **[healing-agent-no-license.md](./healing-agent-no-license.md)** — the **real** blocking-intent path for Surface 4: HA is wanted but the tenant lacks the right consumable pool (Heals vs Test Heals, pool not assigned/enabled, exhausted). Go there when the customer wants HA working and the robot log carries `No available license / Agentic units`.
+- **[no-recovery-data.md](./no-recovery-data.md)** — HA is licensed and engaged but produced **no data** for other reasons (connectivity to Semantic Proxy / LLM Gateway, classic activity, image-only target). Go there when entitlement checks pass, the healing-data archive is genuinely empty, and none of the four surfaces above explains it.
+
+## References
+
+- Healing Agent setup (available by default — recommendations on, self-healing off; GA needs UIA `25.10.2`+): https://docs.uipath.com/agents/automation-cloud/latest/user-guide-ha/setup
+- Healing Agent prerequisites (UIA `25.10.2`+): 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
+- Healing Agent release notes (preview deprecation — upgrade by 1 Nov 2025; Orchestrator Jobs panel disabled after): https://docs.uipath.com/agents/automation-cloud/latest/release-notes-ha/september-2025
+- Insights — Healing Agent: https://docs.uipath.com/insights/automation-cloud/latest/user-guide/healing-agent