fix #475: guide Windows shell execution and report quoting hazards

[ahmad-ajmal]

What

Windows shell commands can fail or silently produce incorrect output when an agent wraps PowerShell source in another interpreter. Keep concise raw-script instructions in the Windows-only run_shell schema, and report the selected shell, resolved executable and advisory guidance for common nested PowerShell wrappers.

Closes #475. Replaces #476 after renaming the source branch to ahmad/fix-windows-shell-guidance.

Why

A nested $n=2; Write-Output $n loses its variables before the inner PowerShell executes. A single-quoted -Command wrapper can return exit code 0 while printing the script as a string. The Windows tool schema gives a direct disk-query example, and nested-call results advise verifying stdout even on success.

Shared system context and AGENT.md stay unchanged. Preserve native stderr and exit codes instead of guessing error types from stderr keywords. Explicit cmd, default/auto routing and intentional nested execution retain their behavior; submitted commands are never rewritten or retried automatically.

How to test

• python -m unittest discover -s tests/windows_shell -v — 17 tests pass locally on Windows. Includes seven direct-script cases each on Windows PowerShell and pwsh, the disk query, both silent-output reproductions, native parser errors, application-defined stderr, successful stderr, cmd compatibility, nonzero exits, timeout registration/cleanup and background completion.
• ruff format --check . and ruff check . with Ruff 0.16.1 — repository-wide checks pass.
• git diff --check — passes.

A focused Windows CI workflow runs the tests using only the Python standard library. They execute the production function source with real OS processes, while stubbing Node PATH preparation and cancellation registration. Full user-triggered cancellation and an end-to-end LLM retry-count comparison are not covered.

Scope

Guidance recognizes common nested powershell/pwsh -Command wrappers. It is advisory and does not establish whether arbitrary successful output is correct. The existing direct -Command transport passed the reproductions, so this change does not introduce EncodedCommand or temporary scripts.