flask-debug-cross-worktree-edit-stale

Flask debug edits cross-worktree stale

Problem

You're running a Flask dev server (python app.py with debug=True, or flask run --debug) from one git worktree. You're editing template / static / view files from a sibling worktree of the same repo, because the branch you want to ship is checked out at the running worktree and git checkout <branch> fails in your editing worktree.

You hit curl http://127.0.0.1:PORT/the-page after each edit, and the response bytes don't change. You hypothesize Jinja bytecode cache, Flask @_ttl_cache, browser caching, CDN, or stale __pycache__. You try touch app.py to bust Flask's debug-reload, restart the process, clear browser cache. Nothing fixes it.

Root cause: git worktrees have independent working trees on disk. Each git worktree directory has its own copy of every tracked file. Flask is reading from <worktree-A>/templates/page.html. Your edits live in <worktree-B>/templates/page.html. They're physically different files; the dev server has no way to see B's edits until A's disk state changes.

Trigger conditions (high-confidence diagnosis)

Fire this skill when ALL of these are true:

1. git worktree list shows ≥2 worktrees of the same repo.
2. A dev server is bound to a known port; lsof -i :PORT shows the server process.
3. The server's CWD (lsof -p <PID> | grep cwd, or check the script that launched it) is in worktree A.
4. Your editor is making changes in worktree B (different path, same repo).
5. curl against the page returns byte-identical responses despite confirmed-saved edits in worktree B.
6. The file you're editing is tracked (git knows about it) — not a new untracked file. (Untracked files exist in only one worktree anyway.)

If condition 6 is FALSE (you created a new file), the new file simply doesn't exist in worktree A's tree. Same root cause, different shape: either commit + ff-merge into A's branch, or create the file in A.

Diagnostic recipe

# 1. Confirm cross-worktree mismatch
diff -q \
  <(grep "your-recent-edit-marker" "<worktree-A>/path/to/file") \
  <(grep "your-recent-edit-marker" "<worktree-B>/path/to/file")
# Files differ → confirmed.
# Files match → look elsewhere (TTL cache, CDN, etc.).

# 2. Confirm Flask is actually reading from A
lsof -p $(lsof -ti :PORT | head -1) | grep "cwd\|<worktree-A>"

# 3. Check git state of A
git -C "<worktree-A>" rev-parse HEAD
git -C "<worktree-A>" status -sb
# What branch is A on? Are there uncommitted changes that would conflict
# with merging your work in?

Solution

Three fixes, in order of safety + ease:

Fix 1 — ff-merge your branch into A's branch (recommended)

If A has a clean working tree and is checked out on a branch your work should land on (e.g., the wip branch), commit your edits in B and fast-forward-merge into A.

# In worktree B (where you're editing):
git -C "<worktree-B>" add <files>
git -C "<worktree-B>" commit -m "..."

# Then ff-merge into A's branch (run from B is fine; --ff-only refuses
# any non-trivial merge so it's safe):
git -C "<worktree-A>" merge --ff-only <your-branch>

Flask debug-reload watches the disk and picks up the changed files on next request. Done.

This is also the right move when the user wants the work merged into the wip branch anyway — preferable to polluting A with WIP commits.

Fix 2 — Move Flask to your worktree

Stop the dev server in A; start it in B from your branch directly. Costs you the convenience of running from the "blessed" worktree but eliminates the cross-worktree gap entirely.

# Stop A's server
lsof -ti :PORT | xargs kill -9

# Start in B
cd "<worktree-B>/<dashboard-dir>"
python3.11 app.py    # or flask run --debug --port PORT

Fix 3 — Sync files manually (debugging only)

For a one-off probe (e.g., "does my CSS edit even render?"), copy the single file across:

cp "<worktree-B>/static/css/foo.css" "<worktree-A>/static/css/foo.css"

Don't use this as a workflow. It silently overwrites whatever's in A and creates divergence-from-git that's easy to forget. Only use to prove the diagnosis before committing to Fix 1 or Fix 2.

Verification

After applying Fix 1 or Fix 2:

curl -s "http://127.0.0.1:PORT/page" | grep "your-recent-edit-marker" | wc -l
# > 0  → fix worked, dev server now serves your edits
# 0    → still stale; check Flask log for reload errors, or escalate
#         to the sister TTL-cache skill

Why cache-bust tricks fail (and which skill to use instead)

Symptom	Wrong skill	Right diagnosis
touch app.py doesn't help	flask-debug-ttl-cache-stale-after-rebake (Flask TTL cache)	This skill — file-level divergence
Browser shows old version after server restart	Browser cache	This skill — server is reading A, browser is correctly receiving A's content
Restart Flask, still stale	Bytecode cache	This skill — file system, not Python state
git status in B shows clean tree but page still old	Git confusion	This skill — A's tree is independent of B's

The fast disambiguation: does worktree A's working tree have your edit? If no, it's this skill. If yes, look elsewhere.

Example

Real session 2026-05-08 (this is where the skill was extracted):

• Primary worktree (/Users/.../the-project-repo) had wip/monitor-noapp-cohort-broaden checked out, Flask running on :8006 from there.
• Sister worktree (.claude/worktrees/monitor-prettify) was where edits were being made.
• After 5 polish edits to templates/roadmap.html, curl returned byte-identical 27,028 bytes every time.
• Confused for ~3 minutes by hypotheses around Jinja cache, Flask TTL, etc.
• Diagnosis: grep "miscounted in training" <worktree-A>/...html → 0 hits. grep "miscounted in training" <worktree-B>/...html → 3 hits. Confirmed disk divergence.
• Fix: committed in B, ff-merged into wip from primary. Next curl saw the polish.

Result: page served correctly within ~1 second of the merge (Flask debug-reload caught the file change).

Notes

• This is NOT a Flask bug. Every dev server with file-watching (Django runserver, Rails server with Spring, etc.) has the same shape. The skill name says Flask because that's where it was observed, but the diagnostic procedure and fixes generalize.
• macOS / Linux only. Windows + git worktrees has additional subtleties (CRLF translation, junction points) not covered here.
• The diagnostic is fast. A single diff -q between worktree paths confirms the hypothesis in <1 second. Don't hypothesize for 3 minutes like the original session did — diff -q first.
• Auto-docs hooks may help OR hurt. If your project has a hook that auto-syncs files, it can either propagate your B-side edits to A automatically (helpful) or revert them (frustrating). Check whether such a hook exists; if so, consider whether to commit through it or work around it.

See also

• flask-debug-ttl-cache-stale-after-rebake — genuine TTL-cache trap in Flask, distinct mechanism (in-process cache, not filesystem divergence). Use that skill when worktrees agree on disk but Flask still serves old responses.
• gh-pr-merge-worktree-checkout-trap — git-side error that prevents you from git checkout-ing the same branch in two worktrees. Forces you into the cross-worktree edit pattern this skill diagnoses.
• deploy-from-stale-worktree-silent-rollback — production sibling pattern: Cloud Run / Docker build context = local filesystem, so deploying from worktree A bakes A's stale state into the image. This skill's localhost-Flask analogue.
• worktree-index-corrupt-async-post-commit-hook — different worktree trap: corrupt index after async post-commit hooks. Use that skill when git status itself errors with unable to read <sha>.

References

• Git docs on git-worktree(1): each worktree has its own HEAD, index, and working tree but shares the object store. https://git-scm.com/docs/git-worktree
• Flask debug=True reloads on file-watcher events; the watcher scans the process's CWD tree, not "the repo". https://flask.palletsprojects.com/en/latest/server/