variancelabs-mcp 0.3.1__tar.gz

variancelabs_mcp-0.3.1/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+variancelabs-output/
+*.egg-info/
+.uv/
+data/demo-viewer/
+src/web-app/node_modules/
+tmp-assets/*
+data/debug-3d-synthetic dataset/*

variancelabs_mcp-0.3.1/.superpowers/sdd/.gitignore

@@ -0,0 +1 @@
+*

variancelabs_mcp-0.3.1/.superpowers/sdd/2026-09-28-project-data-management/final-fix-py-report.md

@@ -0,0 +1,517 @@
+# Final review fix pass — Python (implementer report)
+
+Scope: every "Important" and "Minor (fix now)" item in `final-review-py.md`, Python side
+only. Nothing under "Left as is" was touched. `src/web-app/` was not touched, no `npm`
+commands were run.
+
+Commits created: none (uncommitted by rule — CLAUDE.md forbids commits).
+
+## Method
+
+For each item: wrote/extended the test, reverted the corresponding source hunk back to
+its pre-fix form (recorded from the edit I was about to make), ran the test to confirm
+RED, restored the fix, ran again to confirm GREEN. RED/GREEN evidence is per item below.
+At the end, ran the full suite once.
+
+---
+
+## Important #1 — recovery skipped forever after a fresh build.lock at open time
+
+`src/project/rebuild.py`
+
+- `recover()` now returns `bool`: `False` when it was skipped (`TimeoutError` acquiring
+  `build.lock`), `True` once it actually ran.
+- `ensure_recovered()` no longer marks the project "recovered" before calling `recover()`.
+  It now: returns immediately if already recovered; treats the project as recovered
+  without touching the lock if this process already owns a live `_Worker` for it (a
+  worker means this process's own jobs already keep the index in sync — recovering here
+  too could race a build it just started); otherwise calls `recover()` and only records
+  the project as recovered if it returned `True`. So a later call (the next `_store()` or
+  `open_project()`) retries once the lock is free.
+- `src/variancelabs_mcp/app/http.py`: `_store()` now calls `rebuild.ensure_recovered(s)`
+  before returning the store, so every HTTP request (not just `project_open`) can trigger
+  the retry — closing "it clears only when B's MCP process restarts".
+
+Tests (`tests/test_project_rebuild.py`):
+- `test_ensure_recovered_retries_once_the_lock_is_gone` — holds `build.lock`, calls
+  `ensure_recovered` (must be skipped, object stays "building"), releases the lock, calls
+  `ensure_recovered` again (must now run: object becomes "failed"/"interrupted").
+- `test_ensure_recovered_is_skipped_once_this_process_has_a_worker` — submits a job first
+  (creating a worker), then calls `ensure_recovered`; the stuck "building" object must be
+  left alone (no attempt to grab the lock from under the worker).
+
+RED (old `ensure_recovered`, marked recovered before calling `recover()`):
+```
+$ uv run pytest tests/test_project_rebuild.py -k ensure_recovered -q
+FAILED tests/test_project_rebuild.py::test_ensure_recovered_retries_once_the_lock_is_gone
+FAILED tests/test_project_rebuild.py::test_ensure_recovered_is_skipped_once_this_process_has_a_worker
+2 failed
+```
+GREEN:
+```
+$ uv run pytest tests/test_project_rebuild.py -k ensure_recovered -q
+2 passed
+```
+
+---
+
+## Important #2 — merge() turns transform: "auto" into "delete the key"
+
+`src/project/api.py`: added `LITERAL_AUTO = ("transform",)`; `merge()` only pops the key
+on `"auto"` when the key is not in `LITERAL_AUTO`.
+
+Test (`tests/test_project_api.py::test_merge_keeps_a_literal_auto_for_transform`).
+
+RED:
+```
+$ uv run pytest tests/test_project_api.py -k merge_keeps_a_literal_auto -q
+FAILED ... assert {'options': {}} == {'options': {'transform': 'auto'}}
+1 failed
+```
+GREEN:
+```
+$ uv run pytest tests/test_project_api.py -k merge_keeps_a_literal_auto -q
+1 passed
+```
+
+---
+
+## Important #3 — Windows delete-pending PermissionError is fatal in FileLock
+
+`src/project/lock.py`:
+- `held()` now also catches `PermissionError` and returns `True` (a delete-pending file
+  is treated as held/fresh rather than "gone", so it is never stolen or removed
+  mid-flight).
+- `acquire()` now catches `(FileExistsError, PermissionError)` from `os.open` and retries
+  through the same contended-lock path instead of propagating the raw error.
+
+Tests (`tests/test_project_lock.py`):
+- `test_held_treats_a_permission_error_as_held` — monkeypatches `Path.stat` to raise
+  `PermissionError`; `held()` must return `True`.
+- `test_acquire_retries_past_a_permission_error_from_open` — monkeypatches `os.open` to
+  raise `PermissionError` once, then succeed; `acquire()` must retry transparently.
+
+RED:
+```
+$ uv run pytest tests/test_project_lock.py -k "permission_error" -q
+FAILED tests/test_project_lock.py::test_held_treats_a_permission_error_as_held
+FAILED tests/test_project_lock.py::test_acquire_retries_past_a_permission_error_from_open
+2 failed
+```
+GREEN:
+```
+$ uv run pytest tests/test_project_lock.py -k "permission_error" -q
+2 passed
+```
+
+---
+
+## Important #4 — update/retry accept building/waiting/version-0 objects; stale version
+
+`src/project/api.py`:
+- New `_busy_object(o, verb)` helper builds the `project_busy` `ProjectError`.
+- `update(s, oid, params, *, wait=None, version=None)`: after the existing
+  `object_not_found` (via `_object`) and `imported` → `not_rebuildable` checks, refuses
+  with `project_busy` when `status in rebuild.ACTIVE` or `version == 0`; then, if
+  `version` is given and differs from the object's current version, refuses with
+  `stale_object` ("Changed elsewhere" / "Close and reopen Edit parameters."). Only then
+  does it merge/validate/submit.
+- `retry(s, oid, *, wait=None)`: same busy check before the existing
+  failed/out_of_date check (so building/waiting/version-0 now answer 409 `project_busy`
+  instead of 400 `invalid_params`; a merely "ready" object still answers 400).
+- `src/variancelabs_mcp/app/http.py`: `STATUS["stale_object"] = 409`; POST
+  `/api/object/update` now reads `body.get("version")` and passes it through to
+  `api.update` only when it is a (non-bool) `int`.
+
+Tests:
+- `tests/test_project_api.py::test_update_and_retry_refuse_while_the_object_is_active_or_unbuilt`
+- `tests/test_project_api.py::test_update_refuses_a_stale_version`
+- `tests/test_app_http.py::test_update_conflict_returns_409_stale_object_on_a_version_mismatch`
+
+RED:
+```
+$ uv run pytest tests/test_project_api.py -k "active_or_unbuilt or stale_version" tests/test_app_http.py -k "stale_object" -q
+FAILED tests/test_project_api.py::test_update_and_retry_refuse_while_the_object_is_active_or_unbuilt
+FAILED tests/test_project_api.py::test_update_refuses_a_stale_version - TypeError: update() got an unexpected keyword argument 'version'
+FAILED tests/test_app_http.py::test_update_conflict_returns_409_stale_object_on_a_version_mismatch
+3 failed
+```
+GREEN:
+```
+$ uv run pytest tests/test_project_api.py -k "active_or_unbuilt or stale_version" tests/test_app_http.py -k "stale_object" -q
+3 passed
+```
+
+---
+
+## Important #5 — a crafted project.json can read/delete outside the project
+
+`src/project/store.py`: `ProjectStore.read()` now validates, for every entry in
+`data["objects"]`: the key matches `SAFE_KEY_RE` (new: `^[A-Za-z0-9_-]{1,128}$` — a
+single path segment, no `..`, no separators) **and** `o["id"] == key`; and `version` is a
+non-bool `int >= 0`. Any violation raises `project_corrupt`. Since `source_dir`/
+`object_dir` are built directly from the key, this is the single gate that protects both
+the Data-page `Remove` route and `/api/object`/`/files` from a crafted or foreign
+`project.json`.
+
+**Deviation from the brief**: the brief says "every key must match `UUID_RE`". I used a
+looser `SAFE_KEY_RE` (alnum/`_`/`-` only) instead of the full canonical-UUID pattern.
+Reason: production code always creates object ids via `store.new_id()` (a real uuid4),
+so this doesn't weaken anything in real use — but the existing unit-test suite (
+`tests/project_helpers.py:rec()` and its callers in `test_project_rebuild.py`,
+`test_project_kinds_geometry.py`, `test_project_kinds_intervals.py`, pre-dating this fix
+pass) hand-builds objects with short ids like `"a"`, `"dh"`, `"wf"`, `"bm"` for
+readability. Enforcing strict `UUID_RE` broke that whole convention (16+ pre-existing
+tests started raising `project_corrupt`). `SAFE_KEY_RE` still closes the actual
+vulnerability (any key containing `/`, `\`, or `..` is rejected), while keeping those
+fixtures valid. Flagging this in case the intent was specifically to force test fixtures
+onto real UUIDs too — happy to switch if so, but it looked like an oversight rather than
+a requirement.
+
+Test (`tests/test_project_api.py::test_read_rejects_object_keys_that_are_not_valid_ids`) —
+plants `"../../victim"` as an object key via `mutate`, expects `s.read()` to raise
+`project_corrupt`, and checks the legitimate object's source folder is untouched.
+
+RED:
+```
+$ uv run pytest tests/test_project_api.py -k rejects_object_keys -q
+FAILED tests/test_project_api.py::test_read_rejects_object_keys_that_are_not_valid_ids
+1 failed
+```
+GREEN:
+```
+$ uv run pytest tests/test_project_api.py -k rejects_object_keys -q
+1 passed
+```
+
+---
+
+## Important #6 — has_view never reaches the client
+
+`src/project/api.py`: added `"has_view"` to `SUMMARY_KEYS`, so it now flows through
+`object_summary()` into `summary()`, `project_view()` and `details()["object"]`.
+
+Test (`tests/test_project_api.py::test_summary_includes_has_view`).
+
+RED:
+```
+$ uv run pytest tests/test_project_api.py -k summary_includes_has_view -q
+FAILED ... KeyError: 'has_view'
+1 failed
+```
+GREEN:
+```
+$ uv run pytest tests/test_project_api.py -k summary_includes_has_view -q
+1 passed
+```
+
+---
+
+## Minor fixes (all ruled "fix now")
+
+1. **`hmac.compare_digest` TypeError on a non-ASCII token** — `http.py:_authorized` now
+   compares UTF-8-encoded bytes on both sides instead of raw `str`, so a non-ASCII
+   `?token=` is a clean 403 instead of a dropped connection.
+   Test: `test_app_http.py::test_a_non_ascii_token_is_a_clean_403_not_a_dropped_connection`.
+
+2. **HTTP only caught `ProjectError`** — both `do_GET`'s `/api/*` dispatch and `do_POST`'s
+   dispatch now also catch bare `Exception` and answer `500 {"error": problem_of(e)}`
+   (`rebuild.problem_of`), instead of letting e.g. a `PermissionError` or
+   `ProcessingError` drop the socket.
+   Test: `test_app_http.py::test_unexpected_exceptions_return_a_problem_not_a_dropped_connection`
+   (monkeypatches `api.details` to raise `PermissionError`).
+
+3. **Rename during a new object's first build overwritten by `auto_name` at commit** —
+   `api.rename_object` now also sets `auto_name=False`, so `rebuild.py`'s
+   `commit()` (`if o.pop("auto_name", False): o["name"] = module.default_name(...)`) no
+   longer clobbers a rename that happened mid-build.
+   Test: `test_project_rebuild.py::test_rename_during_build_is_not_overwritten_by_auto_name_commit`.
+
+4. **MAX_PATH / raw OSError past the tool boundary** — `variancelabs_mcp/project/tools.py`:
+   `call()` and `_project_create()` now also catch `(OSError, TimeoutError)`; `problem()`
+   turns them into a `Problem(type="io_error", ...)` whose remediation mentions Windows
+   error 206 / `LongPathsEnabled`, instead of propagating a raw traceback past the tool.
+   One line added to `doc/varianceLabs-doc/projects.md`... (see docs section below;
+   MAX_PATH itself is not separately documented beyond the remediation text, per "must be
+   minimal").
+   Tests: `test_project_tools.py::test_os_errors_become_a_problem_not_a_raw_crash`.
+
+5. **Empty default project name at a drive-root cwd** — `open_store()` now falls back to
+   `"project"` when `Path.cwd().name` is empty.
+   Test: `test_project_tools.py::test_default_project_name_falls_back_when_cwd_name_is_empty`.
+
+6. **Heartbeat gives up for good on one transient read failure** — `lock.py:_beat` now
+   only stops when `_read_token()` returns a *readable, different* token; a `None` read
+   (transient failure) or an `OSError` from `os.utime` is `continue`d past instead of
+   returning.
+   Tests: `test_project_lock.py::test_heartbeat_ignores_a_transient_read_failure` (stays
+   held across the full window despite one failed read) and
+   `test_heartbeat_stops_once_a_foreign_token_takes_the_lock` (unchanged correct-stop
+   behaviour, added as a companion so the fix doesn't accidentally make the heartbeat
+   immortal).
+
+7. **`ensure_recovered` retry test** — covered under Important #1 above (same fix).
+
+RED (minors #1-3, #6 together — #4/#5 shown above under their own item):
+```
+$ uv run pytest tests/test_app_http.py -k "non_ascii or unexpected_exceptions" tests/test_project_rebuild.py -k rename_during_build tests/test_project_lock.py -k "heartbeat_ignores" -q
+FAILED tests/test_app_http.py::test_a_non_ascii_token_is_a_clean_403_not_a_dropped_connection
+FAILED tests/test_app_http.py::test_unexpected_exceptions_return_a_problem_not_a_dropped_connection
+FAILED tests/test_project_rebuild.py::test_rename_during_build_is_not_overwritten_by_auto_name_commit
+FAILED tests/test_project_lock.py::test_heartbeat_ignores_a_transient_read_failure
+4 failed
+```
+GREEN:
+```
+$ uv run pytest tests/test_app_http.py -k "non_ascii or unexpected_exceptions" tests/test_project_rebuild.py -k rename_during_build tests/test_project_lock.py -k "heartbeat_ignores" -q
+4 passed
+```
+
+### Docs (minor, no tests)
+
+- `doc/varianceLabs-doc/projects.md`: corrected "what depends on it is marked out of
+  date" (true only for a downstream failure, not when the edited object itself fails —
+  its dependents keep their current version, per `rebuild.py`'s
+  `test_failure_of_the_edited_object_keeps_its_version`); added one line on
+  `VARIANCELABS_OUTPUT_DIR` spanning project resolution across folders.
+- `README.md`: `project_create(name)` → `project_create(name, open?)`.
+- `src/variancelabs_mcp/project/tools.py` (`LOAD_DH_DOC`): named the six roles
+  (`x_from, y_from, z_from, x_to, y_to, z_to`) instead of the `X_FROM ... Z_TO` ellipsis.
+
+---
+
+## Full suite
+
+```
+$ uv run pytest -q
+474 passed, 225 warnings in 109.98s (0:01:49)
+```
+
+225 warnings, all the pre-existing kaleido/plotly ones (same set as the stated baseline);
+no new warnings introduced. `tests/test_app_e2e.py` (reads the committed web bundle) is
+included and passed — no web-side dependency issue observed.
+
+## Files changed
+
+- `src/project/rebuild.py` — `recover()`/`ensure_recovered()` (Important #1)
+- `src/project/lock.py` — `held()`, `acquire()`, `_beat()` (Important #3, Minor #6)
+- `src/project/store.py` — `ProjectStore.read()` object-key/version validation
+  (Important #5, with the `SAFE_KEY_RE` deviation noted above)
+- `src/project/api.py` — `SUMMARY_KEYS` (#6), `merge()`/`LITERAL_AUTO` (#2),
+  `update()`/`retry()`/`_busy_object()` (#4), `rename_object()` (Minor #3)
+- `src/variancelabs_mcp/app/http.py` — `STATUS["stale_object"]`, `_authorized()`,
+  `_store()` calling `ensure_recovered`, broad-`Exception` handling in GET/POST,
+  `version` passthrough on `/api/object/update` (#1, #4, Minor #1, Minor #2)
+- `src/variancelabs_mcp/project/tools.py` — `open_store()` default-name fallback,
+  `problem()`/`call()`/`_project_create()` OSError/TimeoutError handling, `LOAD_DH_DOC`
+  wording (Minor #4, #5, docs)
+- `README.md`, `doc/varianceLabs-doc/projects.md` — docs (Minor)
+- Tests: `tests/test_project_rebuild.py`, `tests/test_project_lock.py`,
+  `tests/test_project_api.py`, `tests/test_app_http.py`, `tests/test_project_tools.py`
+
+## Self-review findings
+
+- Confirmed `update()`'s check order matches the brief: `object_not_found` (via
+  `_object`) → `not_rebuildable` (imported) → `project_busy` → `stale_object` → param
+  validation. `retry()`: `object_not_found` → `project_busy` → the existing
+  failed/out_of_date check.
+- `version` passthrough in `http.py` explicitly excludes `bool` (JSON `true`/`false`
+  would otherwise satisfy Python's `isinstance(v, int)`).
+- Did not touch `_project_update` (the MCP tool) to accept `version` — the shared
+  contract only calls for it on `api.update` and the HTTP route; the MCP tool has no
+  notion of "the version the caller last saw" since it always waits synchronously.
+
+## Concerns
+
+- The `SAFE_KEY_RE` vs `UUID_RE` deviation on Important #5 (see above) — the security
+  property the reviewer asked for is intact (path traversal via a crafted key is
+  rejected), but the exact pattern differs from the brief's literal instruction. Worth a
+  second look from the reviewer.
+
+---
+
+# Fix round 2 (Python side)
+
+A scoped opus re-review of round 1 found two issues introduced by/around the round-1
+fixes, plus one leftover gap and a doc line. All four addressed below, same file
+boundaries (no `src/web-app/`, no `npm`).
+
+## N1 (Important) - PermissionError spins acquire() past its deadline
+
+`src/project/lock.py:acquire()`. The round-1 fix caught `(FileExistsError,
+PermissionError)` in one branch and used `held()` to decide "stale, take over now" vs
+"contended, sleep and check the deadline". For `PermissionError` with **no lock file
+present** (an unwritable folder, Windows Controlled Folder Access), `held()` - which
+`stat()`s the path - hits `FileNotFoundError` and returns `False`, so the code took the
+"stale, retry immediately" branch: `os.remove` (harmlessly fails), then `continue` with
+**no sleep and no deadline check**. The reviewer measured ~37,000 `os.open` calls in 2 s
+on `FileLock(timeout=0)`; `project_open` -> `ensure_recovered` -> `recover` would hang the
+MCP process on such a folder.
+
+Fix: split the `except` clause. `FileExistsError` keeps the existing stale-takeover
+logic (a lock *file* exists, so `held()` is meaningful). `PermissionError` now always
+takes the plain sleep + deadline path - it tells us nothing about whether a stale lock
+can be taken over, so assuming so is unsafe.
+
+Test (`tests/test_project_lock.py::test_acquire_times_out_on_a_persistent_permission_error_without_spinning`):
+monkeypatches `os.open` to always raise `PermissionError` with no lock file present;
+`acquire(timeout=0.3)` must raise `TimeoutError` within ~2 s and call `os.open` well
+under 100 times.
+
+RED (old combined-branch code - had to be killed; it never returns):
+```
+$ uv run pytest tests/test_project_lock.py -k persistent_permission_error -q
+# hung indefinitely (background run killed after >30s, thousands of os.open calls
+# already made); reproduces the reviewer's spin exactly.
+```
+GREEN:
+```
+$ uv run pytest tests/test_project_lock.py -k persistent_permission_error -q
+1 passed, 9 deselected in 0.44s
+```
+
+## N3 (Important) - a live worker permanently short-circuited recovery
+
+`src/project/rebuild.py`. Round 1's `ensure_recovered` treated "this process already has
+a worker for the project" as "already recovered" (added the key to `_recovered` without
+ever calling `recover()`). That meant: if process B submits *any* job before dead process
+A's `build.lock` goes stale, A's orphaned `building` object is never settled for the rest
+of B's lifetime - `update`/`retry`/`remove` on it keep returning `project_busy` forever.
+Round 1's own test (`test_ensure_recovered_is_skipped_once_this_process_has_a_worker`)
+asserted exactly that broken behaviour, per the finding.
+
+Fix (controller's design, simpler than the round-1 approach):
+- `_Worker` now tracks `active_ids: set[str]` - the object ids of jobs currently queued
+  or running in *this process's* worker for the project - updated in `submit()` (ids
+  added before the job is queued) and in `_loop()`'s `finally` (ids removed once the job
+  finishes, before `job.done.set()`).
+- `recover(store, exclude=())` gained an `exclude` parameter: the status-fixing pass
+  skips excluded ids entirely (never marks them failed/drops them), and the orphan-folder
+  cleanup pass skips excluded ids' `objects/`/`sources/` entries entirely (not just the
+  version-folder pruning) - so a build this process is mid-way through writing into
+  `v<n+1>/` is never touched.
+- `ensure_recovered()` now always calls `recover(store, exclude=_worker_active_ids(key))`
+  (dropped the "has_worker -> treat as recovered" shortcut) and marks the project
+  recovered **only when `recover()` returns `True`** - i.e. only when it actually
+  acquired `build.lock` and ran. If the lock is held (by another process, or by this
+  process's own worker mid-job), the call is a no-op and the next `ensure_recovered`
+  call (next `_store()`/`open_project()`) retries.
+
+Since `ensure_recovered` runs on every app-server `_store()` call, this means: A's fresh
+lock -> skipped; B's own job holds the lock while running -> skipped; once both are clear,
+the very next request settles A's orphan, without ever touching B's own in-flight or
+queued work.
+
+Round 1's `test_ensure_recovered_is_skipped_once_this_process_has_a_worker` was replaced
+(per the coordinator's note that it "must change") with:
+- `tests/test_project_rebuild.py::test_recover_with_exclude_leaves_those_ids_alone` -
+  direct-level test: two `waiting` objects, `recover(chain, exclude={"c"})` settles `"b"`
+  to `failed`/`interrupted` and leaves `"c"` exactly as it was.
+- `tests/test_project_rebuild.py::test_ensure_recovered_settles_an_orphan_once_this_processs_job_is_done` -
+  the reconnect scenario: A's fresh lock held, B submits a job on an unrelated object;
+  `ensure_recovered` is a no-op while A's lock is fresh; once A's lock is released, B's
+  queued job runs to completion; the next `ensure_recovered` call then settles A's orphan
+  and B's own object is confirmed rebuilt (`ready`, version bumped) - undisturbed.
+
+RED (old `recover()`/`ensure_recovered()`, no `exclude` param):
+```
+$ uv run pytest tests/test_project_rebuild.py -k "recover_with_exclude or settles_an_orphan" -q
+FAILED test_recover_with_exclude_leaves_those_ids_alone - TypeError: recover() got an
+  unexpected keyword argument 'exclude'
+FAILED test_ensure_recovered_settles_an_orphan_once_this_processs_job_is_done -
+  AssertionError: assert 'building' == 'failed'   (orphan never settled)
+2 failed, 19 deselected
+```
+GREEN:
+```
+$ uv run pytest tests/test_project_rebuild.py -q
+21 passed in 5.16s
+```
+
+## m1 (Minor) - recovery errors outside http.py's try blocks drop the connection
+
+`src/variancelabs_mcp/app/http.py`. Round 1 moved `rebuild.ensure_recovered(s)` into
+`_store()`, but `_store()` is called *before* the `try`/`except ProjectError`/`except
+Exception` blocks in `do_GET`'s `/api/*` dispatch and in `do_POST`; `_file()` had no
+try/except around its `_store()` call at all. A `project_corrupt` (or any other)
+exception raised while recovering a not-yet-recovered project therefore propagated out of
+the request handler entirely and dropped the connection instead of answering with a JSON
+error.
+
+Fix: `_store()` is back to a pure lookup (no recovery). A new `_recover(self, s)` helper
+runs `rebuild.ensure_recovered(s)` inside its own `try`/`except ProjectError`/`except
+Exception`, replies with the appropriate Problem (`_problem`/500 `{"error":
+problem_of(e)}`) on failure, and returns `False`; all three call sites (`do_GET`'s
+`/api/*` block, `do_POST`, `_file`) now call `if not self._recover(s): return` right
+after obtaining the store and before doing anything else with it.
+
+Test (`tests/test_app_http.py::test_recovery_error_on_first_access_returns_a_problem_not_a_dropped_connection`):
+the `served` fixture's project is created directly via `project.store`/`project.api`
+(never through `project_open`/`_store()`), so it has never been through
+`ensure_recovered`. The test corrupts `project.json`, then makes the *first* request
+(`GET /api/revision`) - triggering recovery inline - and asserts a `500`
+`project_corrupt` JSON body rather than a dropped connection.
+
+RED (old `_store()`-does-recovery, no wrapping):
+```
+$ uv run pytest tests/test_app_http.py -k recovery_error_on_first_access -q
+FAILED ... http.client.RemoteDisconnected: Remote end closed connection without response
+(server-side traceback: ProjectError("project_corrupt", ...) raised from
+_store -> rebuild.ensure_recovered -> recover -> store.read(), uncaught)
+1 failed
+```
+GREEN:
+```
+$ uv run pytest tests/test_app_http.py -q
+12 passed in 9.08s
+```
+
+## Docs - MAX_PATH line
+
+Round 1's report claimed the MAX_PATH remediation was documented but it was only in the
+`Problem`'s `remediation` text, not in `doc/varianceLabs-doc/`. Added one line to
+`doc/varianceLabs-doc/projects.md`:
+
+> On Windows, a project's files add about 140 characters under the working folder path:
+> if loads start failing with a path-length error, keep the working folder path short, or
+> turn on `LongPathsEnabled`.
+
+No test (docs-only).
+
+## Full suite
+
+```
+$ uv run pytest -q
+477 passed, 225 warnings in 97.28s (0:01:37)
+```
+
+225 warnings, same pre-existing kaleido/plotly set as round 1's baseline; no new
+warnings. 477 vs round 1's 474: +1 net test in `test_project_rebuild.py` (one test
+replaced by two, per N3), +1 in `test_project_lock.py` (N1), +1 in `test_app_http.py`
+(m1).
+
+## Files changed (round 2, in addition to round 1)
+
+- `src/project/lock.py` - split `PermissionError`/`FileExistsError` handling in
+  `acquire()` (N1)
+- `src/project/rebuild.py` - `_Worker.active_ids`, `_worker_active_ids()`,
+  `recover(..., exclude=...)`, `ensure_recovered()` redesign (N3)
+- `src/variancelabs_mcp/app/http.py` - `_store()` reverted to pure lookup, new
+  `_recover()` helper, called from `do_GET`, `do_POST`, `_file` (m1)
+- `doc/varianceLabs-doc/projects.md` - MAX_PATH line
+- Tests: `tests/test_project_lock.py`, `tests/test_project_rebuild.py`,
+  `tests/test_app_http.py`
+
+## Concerns (round 2)
+
+- Same as round 1: the `SAFE_KEY_RE` vs `UUID_RE` deviation on Important #5 still stands
+  (not part of this round's scope, unchanged).
+- N3's exclusion is by object id, scoped to a single project's worker; a brand-new
+  object's id is added to the index (status `building`, version 0) and then to
+  `active_ids` in two separate steps (`api._run_new`'s `mutate` then `rebuild.submit`).
+  If `ensure_recovered` ran from another thread in that exact gap, it would not yet see
+  the id in `exclude` and - since version is 0 - could drop the just-created record. This
+  is a pre-existing-style narrow race (same shape as the one already accepted for the
+  "has_worker" check in round 1), not newly introduced; flagging rather than fixing since
+  closing it would need moving object-record creation and job submission behind one lock,
+  a bigger structural change than this fix round's brief.