RDS Profile & WinRM-Host Triage

Targets Windows RDS session hosts over WinRM (with a CIM-over-DCOM fallback). The bundled scripts/Invoke-RdsProfileTriage.ps1 collects read-only health data, computes deterministic severity-ranked findings, and renders a uniform triage report itself — so the output is identical every run and the agent just relays it (and decides remediation). The script never calls an LLM and changes nothing.

SCRIPT = this skill's scripts/Invoke-RdsProfileTriage.ps1. It requires PowerShell 7+ (pwsh).

Why this skill exists (the gotchas it encodes)

RDS profile triage is a minefield of measurement traps that produce confident-but-wrong root causes. This skill bakes the corrections in — read the `caveats` array in the output before concluding anything, and see REFERENCE.md for the full list. The big four:

1. REG_EXPAND_SZ expansion. Reading the roaming-profile path with Get-ItemProperty expands `%USERNAME%` in the calling account's context. Read as admin, a perfectly correct \\FS01\profiles$\%USERNAME%\... looks hardcoded to the admin — a classic false "the GPO is broken" call. The script reads it raw; trust roaming_profile.machine_profile_path_raw.
2. Double-hop. From a non-domain-joined / workgroup operator box, WinRM uses NTLM and the host can't delegate to the file server → roaming load fails with "Access is denied" — for your connecting account only. Those Event 1521s are your artifact, not a user outage. The script tags them user_class=self_or_admin.
3. One noisy account ≠ the whole farm. A single backup/batch service account can mint thousands of temp profiles. The script groups profile-failure events by the real user so you don't generalize one service account's churn into a farm-wide outage.
4. The "Element not found" chain. Corrupt ProfileList entries (empty ProfileImagePath, .bak pointing at deleted temp dirs) → the user profile can't be built → wsmprovhost never registers its COM class → WinRM "could not launch a host process" (Event 86) + DCOM 10000 "error 0". So a broken WinRM endpoint can be a profile problem. The script detects the corruption and the host-launch events together.

How to run

Always run with pwsh. The script prompts for the tier-admin credential (reused for all hosts, never stored). Parse the JSON on stdout.

# Single host, last 24h
pwsh -File SCRIPT -ComputerName RDS01

# Two-host farm, 48h window, full detail to a file
pwsh -File SCRIPT -ComputerName RDS01,RDS02 -Hours 48 -OutFile C:\ops\rds.json

# The host's own WinRM is dead ("could not launch a host process") — go in over DCOM
pwsh -File SCRIPT -ComputerName RDS01 -Protocol Dcom

Output contract

The script does the formatting so every run looks the same — the agent does not re-summarize.

• `-Format text` (default) → a deterministic, uniform plain-text report on stdout, with fixed sections: header, == FINDINGS (ranked) ==, == PER-HOST ==, == COVERAGE GAPS ==, == CAVEATS ==. This is the output you relay.
• `-Format json` → full JSON (or, with -OutFile, a compact summary on stdout + full detail in the file).
• `-Format both` → the text report, then --- JSON ---, then the JSON.
• `-OutFile` always writes the full-detail JSON to the file, whatever -Format is.

JSON key fields (for -Format json/digging): summary.findings, summary.failures (each with a hint), per host roaming_profile.machine_profile_path_raw, hive_leak, temp_profiles, profilelist, profile_events (grouped by user + user_class), winrm_host_launch, and the top-level caveats. Full schema in REFERENCE.md.

What you (the agent) do with the result

Keep it minimal — the report is already uniform and complete:

1. Run the script (default -Format text) and relay the report as-is. Do not reformat, re-rank, or re-summarize it — that's the script's job and the whole point of consistent output. At most add a one-line lead.
2. Act on the one piece of judgement the script can't: if a host shows FAILED - ... could not launch a host process, re-run that host with `-Protocol Dcom` (the report's hint says so) and relay the second report.
3. Honor the `== CAVEATS ==` section when the user asks "so what's the cause" — they are the guardrails (self_or_admin = your double-hop, service_account churn ≠ farm outage, RAW roaming path, the Element-not-found chain). Don't contradict them.
4. Propose remediation only on request (reboot to clear leaked hives, back-up-then-remove corrupt ProfileList entries, clean temp sprawl, exclude service accounts from roaming) — and confirm before changing anything. This skill itself changes nothing.

Errors

• Get-Credential cancelled → re-run and supply the tier-admin credential.
• "could not launch a host process" on a host → its WinRM endpoint is down (often ProfileList corruption). Re-run that host with -Protocol Dcom; check profilelist in the result.
• Workgroup / cross-domain (TrustedHosts message or 0x80090311) → run from a domain-joined admin host, or add the FQDNs to WinRM TrustedHosts (scope to specific hosts, not *), or use -Protocol Dcom. See REFERENCE.md.
• pwsh not found → install PowerShell 7 (winget install Microsoft.PowerShell); the repo installer auto-installs it.