cppa-cursor-browser: make multi-worker set-workspace propagate or fail loudly

[clean6378-max-it]

Sprint Item

#5 of 8 — Medium severity — after #4 (Tuesday PR 2 of 2)

Block Relations

Blocked by	#4 — reuse the shared {error, code} helper for the multi-worker failure response
Blocks	—
Repo/day	Independent of Monday #1–#3 and #6–#8

Calendar Day

Tuesday, July 21, 2026 (PR 2 of 2)

Planned Effort

3 story points (Medium) — sprint item #5

Problem

Under gunicorn --workers N, POST /api/set-workspace silently updates only the worker that served the request — _workspace_path_override is module-level process memory — yet it returns success. The other workers keep serving the old workspace, and the operator gets a false OK with no signal that the change did not take effect fleet-wide.

Goal

One PR that makes the endpoint honest under multiple workers: either propagate the change across workers, or (preferred) return a clear, machine-distinguishable failure instructing the operator to use WORKSPACE_PATH / --base-dir. Single-process behavior stays unchanged.

Scope

Part A — endpoint honesty (prefer fail-loud)

• When the change cannot apply across workers, stop returning plain success. Return a distinguishable failure (with a stable code, using the shared helper from item Fix app.py and scripts/export.py CLI: switch to argparse, add --port/--host/--base-dir, fix default host, validate --since #4 where available) telling the operator to set WORKSPACE_PATH / --base-dir.
• Cross-process propagation is acceptable only if explicitly wanted; it requires shared state beyond the current threading.Lock and is the larger option — default to fail-loud.

Part B — preserve single-process behavior

• In a single-process deployment, POST /api/set-workspace behaves exactly as today.

Part C — test + docs

• A multi-worker test asserts the chosen behavior (no false success).
• Update DEPLOYMENT.md to document the multi-worker constraint and the WORKSPACE_PATH / --base-dir guidance.

Out of scope

• The structured-error-code helper itself (Tuesday item Fix app.py and scripts/export.py CLI: switch to argparse, add --port/--host/--base-dir, fix default host, validate --since #4) — reuse it; do not redefine it.

Acceptance Criteria

• The endpoint no longer reports plain success when the change cannot apply across workers.
• It either propagates the change or returns a clear, machine-distinguishable failure pointing at WORKSPACE_PATH / --base-dir.
• Single-process behavior is unchanged.
• A multi-worker test asserts the chosen behavior.
• DEPLOYMENT.md updated.
• CI green; PR approved by at least 1 reviewer.

Verification

cd C:\Users\Jasen\CppAliance\cppa-cursor-browser
.\.venv\Scripts\Activate.ps1
pytest -q tests/test_workspace_path_thread_safety.py
pytest -q

• Manual: run with gunicorn --workers 2, POST /api/set-workspace → response is a distinguishable failure (or verified propagation), never a bare success.