docs(stormtest): document Windows reload-churn limitations + pathing (#512)

Reads/writes concurrency is platform-agnostic and works on Windows, but
reload churn (SS_RELOAD=1, the default) currently does not. Against a
plugin-managed server the harness wedges past CALL_TIMEOUT when the server
is killed mid-reload under load (#513); the documented "run the server
externally" mitigation also fails on Windows because serve-this-worktree is
bash-only and a hand-started --reload server gets killed by the reload (#514).
The editor itself survives reloads. Also documents the POSIX->Windows
invocation differences (venv path, $TMPDIR -> %TEMP%). Resilience tracked
in #509.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: dsarno

AGENTS.md

@@ -288,6 +288,8 @@ SS_URL=http://127.0.0.1:8010/mcp .venv/bin/python script/stormtest.py  # target
 
 To stress a *branch's* code (plugin + server), point a Godot editor at that worktree's `test_project/` and serve its `src/` via `script/serve-this-worktree` (external server, so `editor_reload_plugin` exercises reload without killing the server), then run stormtest against it. A full JSON snapshot lands in `$TMPDIR/stormtest_report.json` (override with `SS_REPORT`), flushed every few seconds so a crash/kill still leaves data. A small `EDITOR_NOT_READY` / `NODE_NOT_FOUND` / `CONNECTION` error rate is expected noise under concurrency + reloads — watch instead for the process dying, a reload that never recovers, or one op with pathological error/latency.
 
+On Windows, a reads-dominant run (`SS_RELOAD=0`) works, but **reload churn (`SS_RELOAD=1`, the default) currently wedges the harness** and the external-server mitigation doesn't apply (`serve-this-worktree` is bash-only; a hand-started external `--reload` server gets killed by the reload). The editor itself survives reloads — only the harness hangs. Use `.venv\Scripts\python.exe` and note `$TMPDIR` is `%TEMP%`. See the "Windows / cross-platform notes" callout in `docs/STRESS_TESTING.md` (issues #513 / #514; resilience tracked in #509).
+
 **Guardrails built into the test runner:**
 - **Zero-assertion detection**: Tests that complete with 0 assertions are flagged as failures ("Test completed with 0 assertions — likely skipped its logic"). This catches tests that silently `return` before asserting anything.
 - **Resilient discovery**: If a `.gd` file fails to load (parse error, duplicate method, wrong base class), the rest of the suites still run and the failing files are reported in `load_errors`.

docs/STRESS_TESTING.md

@@ -63,6 +63,43 @@ SS_RELOAD=0 SS_WORKERS=4 SS_WAVES=3 .venv/bin/python script/stormtest.py
 SS_URL=http://127.0.0.1:8010/mcp .venv/bin/python script/stormtest.py
 ```
 
+### Windows / cross-platform notes
+
+> ⚠️ **Running on Windows? Reads/writes work; reload churn does not (yet).**
+>
+> **Concurrent reads/writes are fine.** The harness *logic* is platform-agnostic:
+> the in-editor scratch paths (`res://_stormtest/…`) use Godot's virtual
+> filesystem, and the report path goes through `tempfile.gettempdir()` /
+> `os.path.join`, so both resolve correctly on every OS. A reads-dominant run
+> (`SS_RELOAD=0`) is clean on Windows.
+>
+> **Reload churn (`SS_RELOAD=1`, the default) currently does NOT work on Windows**
+> — two independent problems, both tracked:
+> - Against a plugin-managed server, the first `editor_reload_plugin` **wedges the
+>   harness**: the asyncio loop stalls past `CALL_TIMEOUT` when the server is
+>   killed mid-reload under concurrent load. The *editor* survives fine (it
+>   reloads and re-registers a new session) — only the harness hangs. See
+>   [#513](https://github.com/hi-godot/godot-ai/issues/513).
+> - The "run the server externally" mitigation **also fails on Windows**:
+>   `script/serve-this-worktree` is bash-only (no PowerShell port, and it never
+>   passes `--ws-port`), and even a hand-started external `--reload` server gets
+>   **killed by the reload** (`_stop_server` takes down the port owner with no
+>   respawn). See [#514](https://github.com/hi-godot/godot-ai/issues/514).
+>
+>   Until those land, validate reload survival on Windows with a *single-threaded*
+>   reload loop (reload → reconnect → confirm a new `session_id`) rather than the
+>   concurrent churn mode.
+>
+> **Invocation also differs (POSIX → Windows):**
+> - **venv interpreter** — use `.venv\Scripts\python.exe`, not `.venv/bin/python`.
+> - **`$TMPDIR`** in the examples is POSIX; the report lands in the platform temp
+>   dir (`%TEMP%` on Windows). Pass an explicit `SS_REPORT=…` for a known
+>   location, and prefer forward slashes (Python accepts them on Windows and they
+>   dodge backslash-escaping surprises).
+>
+> Making the tooling resilient enough to drop this heads-up is tracked in
+> [#509](https://github.com/hi-godot/godot-ai/issues/509).
+
 ### Knobs (env)
 
 | Var | Default | Meaning |