[FarhanAliRaza]

Split out of #7054. This is the lock only; the opt-in build cache that motivated it is #7455 and is stacked on this.

Problem

Two production exports in the same project (or an export racing a reflex run --env prod start) share .web: the second one rewrites env.json, build/, and the compiled sources while the first is still compiling or zipping, so one of them ships the other's frontend. Review bots on #7054 flagged this for the cache, but it is a pre-existing race.

Changes

• path_ops.json_file_lock (from Prevent concurrent reflex.json update corruption #7052) becomes path_ops.file_lock: one implementation of the platform-specific locking (flock on POSIX, msvcrt.locking on Windows) for files and directories, instead of a second copy for builds. It gains what the build lock needs: nested calls from the same thread reuse the lock, other threads and processes wait, and a forked child drops inherited ownership and waits for its parent. On Windows the lock is released explicitly before the descriptor closes. json_file_lock was never released, so there is no deprecation shim. Serialize concurrent frontend dependency installs #7051 makes the same rename and locks get_web_dir() through it, so the two converge.
• The lock is the existing sidecar in REFLEX_DIR keyed by the resolved .web path, not a file inside .web. Locking never creates .web, and the lock inode survives .web being replaced by reflex init. As with json_file_lock, an unwritable lock directory or an unsupported filesystem logs at debug and proceeds unlocked.
• export.export() holds it from configuration through ZIP creation. Backend-only exports always take it too, since they archive .web/backend; the earlier "only when .web exists" condition existed to avoid creating .web, which the sidecar makes moot, so the race the review bots flagged on that line is closed.
• _run_prod / _run_preview hold it through compile and build and release it before serving.
• Tests: spawned-process serialization and same-thread reentrancy, a second thread waiting, fork ownership, Windows contention retry and release, and a real two-process export test where a backend ZIP waits for the compiler's temporary stateful-pages marker to be renamed.

Measurement

No speedup is claimed. Lock overhead on an unchanged bun export, repeat runs:

	main	this PR
total export	6.90 s	6.84 s
compile phase	0.46 s	0.44 s

This is pure complexity in service of correctness (and of #7455). If the cache is not wanted, the question for this one is only whether the race above is worth fixing.

Measurement setup

Five-page app from the blank template (Radix Themes + Tailwind v4 plugins), Linux x86_64, 4 vCPU, Python 3.14, Node 22.22, npm 10.9, bun 1.4.2. Each run is a fresh interpreter calling reflex.utils.export.export() the same way reflex export does; durations are the phase timings the export already reports to telemetry (compile includes the dependency install). Medians of 3 runs unless noted. Vite dominates every export (~6.5 s); these numbers isolate the part this PR touches.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• This change requires a documentation update

Checklist

• Tests added for the change; tests/units/utils, test_reflex.py, test_prerequisites.py and test_workflow_gates.py pass locally
• ruff check, ruff format --check, codespell, and pyright reflex tests pass locally
• News fragment added for every package touched

https://claude.ai/code/session_018nWB9r2HcC5tkT72UxWgGj
https://claude.ai/code/session_017XAFCkYB3Z8w3S6pgJrLCh

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-06T18:24:53.157193Z	b7d35ca	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[cubic-dev-ai]

All reported issues were addressed across 8 files

<sub>Reply with feedback, questions, or to request a fix.

Turn on auto-fix | Re-trigger cubic</sub>

[chatgpt-codex-connector]

💡 Codex Review

reflex/reflex/utils/export.py

Line 69 in b7d35ca

if frontend or (backend and zipping and web_dir.is_dir())

Lock backend exports before checking for .web

When a backend-only export starts while .web is absent and a concurrent frontend export creates it immediately after this is_dir() check, the backend export proceeds under nullcontext(). build.zip_app() later globs .web/backend/*, so it can archive missing or partially written compiler artifacts while the frontend process believes it owns the workspace lock. The existence check and decision about whether generated backend files may be included must be synchronized to close this first-build race.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[greptile-apps]

Confidence Score: 4/5

[Medium impact] The change reaches production export and frontend-start workflows that share a `.web` directory.

The reported import failure in stacked PR #7455 still needs to be addressed before the two PRs can merge together.

Summary

This PR makes production exports and startup builds wait when they share .web.

• One shared lock now covers files and folders.
• Production exports wait for other work using the same .web folder.
• Production and preview starts lock .web during their first frontend build.

_{Reviews (4) · Last reviewed commit: "Keep the export race test's lock directo..." · Reviewed by Greptile}

[codspeed]

Merging this PR will not alter performance

⚠️ 13 benchmarks spent significant time in system calls

System calls cannot be consistently instrumented, so they are not included in the measure, which understates the real cost. Please switch to the Walltime instrument to accurately measure system calls.

Measurement and system calls

• test_import_cli
• test_cli_startup[run_help]
• test_get_state[memory]
• test_cli_startup[help]
• test_cli_startup[version]
• test_get_state[disk]
• test_set_state[disk]
• test_modify_state[disk]
• test_cli_startup[deploy_help]
• test_state_manager_memory_warm_get
• …and 3 more

✅ 148 untouched benchmarks

---

_{Comparing farhan/frontend-workspace-lock (47eb606) with main (d3f8ccb)}

[masenf]

should consolidate locking implementation with existing json_file_lock so we don't have multiple code paths handling platform-specific file locking in slightly different ways

[cubic-dev-ai]

All reported issues were addressed across 11 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>