feat: add a Windows PowerShell soak harness

[hatayama]

Adds scripts/soak-loop.ps1, a Windows port of the endurance harness, and the doc updates that go with it. scripts/soak-loop.sh samples metrics with ps/pgrep/perl and needs jq, so the soak could not run on Windows at all.

Same iteration plan and the same commands.csv / metrics.csv schema as the shell harness, so results from either platform are comparable.

Platform substitutions

shell	PowerShell
jq	ConvertFrom-Json (no dependency)
ps / pgrep	Win32_Process (unity_rss_kb is Unity.exe's working set)
awk summary	Import-Csv + Group-Object
perl epoch ms	[DateTimeOffset]::UtcNow
sleep+kill watchdog	Start-Process + WaitForExit(ms) + Kill()
trap EXIT	try/finally

Start-Process takes a raw command line, so each argument is quoted against Windows argv rules locally. The script is ASCII-only: Windows PowerShell 5.1 reads a BOM-less UTF-8 script as ANSI and mangled the em dashes in the generated C# comments. All output files are written through UTF8Encoding($false) because Add-Content stamps a BOM onto an empty file. The pause-point line number is derived from the generated ticker source instead of the hand-maintained constant the shell version keeps in sync with its heredoc.

What running it against a real project changed

Most of the branch after the first commit is the harness learning to tell uloop defects from its own noise. Soaking a ~5 GB project, first alone and then three checkouts in parallel:

• Known-benign outcomes are reported as TOLERATED, not FAIL, and counted in a separate summary column. ForceCompileUnknownResult and a completed run-tests whose overall status is Skipped are not defects. commands.csv still records the raw exit code.
• UNITY_SERVER_BUSY is waited out rather than counted. uloop is single-flight, so one slow compile used to fail every command behind it - eight failures from one cause, in all three parallel runs.
• The kill watchdog is configurable (-CommandTimeoutSeconds). The fixed 10 minutes killed two of three parallel runs before their first iteration; a forced recompile of this project measured 842 s / 1139 s / 1204 s under three-way load.
• -CompileWaitTimeoutSeconds forwards --compile-wait-timeout-seconds when the pinned runner accepts it (feat: configurable compile wait timeout and working timeout recovery #2036), detected from compile --help so older runners still work. Passing it lifts the watchdog above the wait.
• Debug code optimization is applied for the pause cycle and restored at the end, and re-applied after every restart - the mode does not survive uloop launch -r, which silently broke every post-restart pause cycle. -KeepCodeOptimization opts out.
• run-tests no longer shares an iteration with compile --force-recompile. Both cadences default to 10, so a full rebuild was always serialised in front of the test run.

Filed from the same runs: #2032 (fixed by #2036) and #2045.

Verification

Every branch was exercised against a stub uloop executable that dumps its argv and can simulate busy, collision, dirty-scene and tolerated-failure responses: argument quoting for paths with spaces and embedded quotes, busy-wait and its exhaustion, compile-retry and its exhaustion, tests deferral, both runner-support branches of the compile-wait flag, and the code-optimization re-apply ordering. Parsed and run under both Windows PowerShell 5.1 and PowerShell 7.

End to end against a real Unity project: 10-iteration solo run, a 5-iteration verification run, and two rounds of three parallel 10-iteration runs. In the last round every command reported 0 failures apart from the pause-point issue that the final commit fixes.

Not included

scripts/soak-loop.sh is unchanged. The tolerated-outcome reporting, the busy wait, the configurable timeouts and the code-optimization handling all apply to it equally, but none of it can be verified on Windows, so mirroring is left as a follow-up rather than shipped untested. docs/soak-testing.md states which behaviours are PowerShell-only.

🤖 Generated with Claude Code

[coderabbitai]

📝 Walkthrough

Walkthrough

Updated soak-testing documentation to cover a PowerShell loop variant, platform prerequisites, invocation parameters, runtime timeout and back-pressure behavior, Debug code-optimization pause points, tolerated failures, and PowerShell-specific results.

Changes

Soak Testing Documentation

Layer / File(s)	Summary
Usage and platform prerequisites docs/soak-testing.md	Introduces the shell and PowerShell variants, documents per-platform requirements, and adds PowerShell quick-start and parameter guidance.
Runtime execution guidance docs/soak-testing.md	Documents binary selection, watchdog and compile-wait timeouts, dispatcher back-pressure, retries, and sequencing of heavy operations.
Pause points and result interpretation docs/soak-testing.md	Explains Debug code-optimization handling, TOLERATED outcomes, summary counters, raw command exit codes, and PowerShell log output.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• hatayama/unity-cli-loop#1989: Introduced the soak-loop harness documentation and shell script that this documentation extends.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding a Windows PowerShell soak harness.
Description check	✅ Passed	The description is directly related to the changeset and accurately describes the new PowerShell harness and docs.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/soak-loop-windows

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

docs/soak-testing.md (1)

43-48: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Show the PowerShell 7 invocation as well.

The example uses powershell, which demonstrates Windows PowerShell 5.1 but not the documented PowerShell 7 path. Add an equivalent pwsh example or explicitly label this command as 5.1-specific.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/soak-testing.md` around lines 43 - 48, Update the soak-testing command
example to also show the equivalent PowerShell 7 invocation using pwsh, or
explicitly label the existing powershell command as Windows PowerShell
5.1-specific while documenting the pwsh path.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@docs/soak-testing.md`:
- Around line 43-48: Update the soak-testing command example to also show the
equivalent PowerShell 7 invocation using pwsh, or explicitly label the existing
powershell command as Windows PowerShell 5.1-specific while documenting the pwsh
path.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 7bf3ac53-45ab-4cc1-965b-b14351d8bcd1

📥 Commits

Reviewing files that changed from the base of the PR and between c0e392c and 0d964fd.

⛔ Files ignored due to path filters (1)

• scripts/soak-loop.ps1 is excluded by none and included by none

📒 Files selected for processing (1)

• docs/soak-testing.md