fix(serve): warn once about ignored PW_SERVE_ALLOWED_HOSTS entries; README FORWARDED_ALLOW_IPS note

[wikithoughts]

Follow-up from the independent review of #43 (item 4 of overnight task W6-passiveworkers-4243fu). Branched from origin/main at f497835, after #43 merged. Items 1–3 are in #45.

What changed

• passiveworkers/serve.py (finding fix(serve,judge): exact-origin check, strict Host, PW_SERVE_ALLOWED_HOSTS; country inside spotlight #43-3, Low): previously, a PW_SERVE_ALLOWED_HOSTS entry that isn't a plain host/IP was dropped silently, so a typo gave a bare 403 forbidden host. Examples: unbracketed IPv6 fd7a::1, *, 0.0.0.0, bad@x. Each such entry now prints one stderr warning per process. That follows the repo's convention: the package has no logging, and other warnings use print(..., file=sys.stderr). main() runs the check once before uvicorn.run, so the warning appears at startup, not on the first request. Allow-list behaviour is unchanged: it still fails closed.
• README.md (finding fix(serve,judge): exact-origin check, strict Host, PW_SERVE_ALLOWED_HOSTS; country inside spotlight #43-2, Low-Medium; one line): a TLS proxy on another machine also needs FORWARDED_ALLOW_IPS=<proxy IP>. uvicorn trusts X-Forwarded-Proto only from loopback by default (FORWARDED_ALLOW_IPS defaults to 127.0.0.1,::1 in the installed uvicorn 0.54.0, uvicorn/config.py:363). Without it, every POST gets 403 forbidden origin.

Verification (run locally, .venv)

• python -m py_compile $(git ls-files '*.py') → exit 0
• ruff check . && pytest tests/ -q --cov=passiveworkers --cov-fail-under=75 → exit 0, 726 passed, 9 skipped, coverage 80.60%
• The new test tests/test_serve.py::test_ignored_allowed_hosts_entries_warn_once_each fails on old code (1 of 1, run with serve.py reverted to origin/main) and passes now. Across three request rounds it checks that each of 4 bad entries warns exactly once, and that valid entries (desk.ts.net, [fd7a::2]:8770) don't warn.
• Real process: I ran PW_SERVE_PORT=18779 PW_SERVE_ALLOWED_HOSTS='desk.ts.net,fd7a::1' python -m passiveworkers.serve on loopback for 6 s. It printed warning: PW_SERVE_ALLOWED_HOSTS entry 'fd7a::1' ignored: … once, before the banner. curl -H 'Host: desk.ts.net' /reports returned 200, and -H 'Host: [fd7a::1]' returned 403, with no repeat warning.

Unverified

• The README FORWARDED_ALLOW_IPS advice was checked against uvicorn's source, not through a real reverse proxy on a second host.
• No browser check: there is no HTML/JS change.
• CI was not watched (not allowed in this lane).

🤖 Generated with Claude Code