fix(dev): exclude runtime state from gateway reload (#3426)

backend/tests/test_dev_entrypoint.py

@@ -40,6 +40,19 @@ def test_entrypoint_script_exists_and_is_posix_sh():
     assert proc.returncode == 0, proc.stderr
 
 
+def test_entrypoint_excludes_runtime_state_from_uvicorn_reload():
+    content = ENTRYPOINT.read_text(encoding="utf-8")
+
+    assert ': "${DEER_FLOW_HOME:=/app/backend/.deer-flow}"' in content
+    assert 'mkdir -p "$DEER_FLOW_HOME" /app/backend/.deer-flow' in content
+    assert "--reload-include='*.yaml .env'" not in content
+    assert "--reload-include='*.yaml'" in content
+    assert "--reload-include='.env'" in content
+    assert "--reload-exclude=/app/backend/sandbox" in content
+    assert '--reload-exclude="$DEER_FLOW_HOME"' in content
+    assert "--reload-exclude=/app/backend/.deer-flow" in content
+
+
 def test_no_uv_extras_yields_empty_flags():
     proc = _run(None)
     assert proc.returncode == 0

backend/tests/test_gateway_runtime_cleanup.py

@@ -43,6 +43,19 @@ def test_service_launchers_always_use_gateway_runtime():
         assert "LANGGRAPH_REWRITE" not in content, path
 
 
+def test_local_dev_gateway_reload_excludes_runtime_state_with_absolute_dirs():
+    serve_sh = _read("scripts/serve.sh")
+
+    assert 'export DEER_FLOW_PROJECT_ROOT="$REPO_ROOT"' in serve_sh
+    assert 'BACKEND_RUNTIME_HOME="$REPO_ROOT/backend/.deer-flow"' in serve_sh
+    assert 'export DEER_FLOW_HOME="$BACKEND_RUNTIME_HOME"' in serve_sh
+    assert 'mkdir -p "$DEER_FLOW_HOME" "$BACKEND_RUNTIME_HOME"' in serve_sh
+    assert "--reload-exclude='$DEER_FLOW_HOME'" in serve_sh
+    assert "--reload-exclude='$BACKEND_RUNTIME_HOME'" in serve_sh
+    assert "--reload-exclude='sandbox/'" not in serve_sh
+    assert "--reload-exclude='.deer-flow/'" not in serve_sh
+
+
 def test_backend_container_only_exposes_gateway_port():
     dockerfile = _read("backend/Dockerfile")
 

docker/dev-entrypoint.sh

@@ -64,6 +64,13 @@ if [ -n "$EXTRAS_FLAGS" ]; then
     echo "[startup] uv extras:$EXTRAS_FLAGS"
 fi
 
+# Keep runtime-owned files out of uvicorn's reload watcher. The directory must
+# exist before uvicorn starts so watchfiles treats it as an excluded directory,
+# not as a plain glob pattern.
+: "${DEER_FLOW_HOME:=/app/backend/.deer-flow}"
+export DEER_FLOW_HOME
+mkdir -p "$DEER_FLOW_HOME" /app/backend/.deer-flow
+
 # ── Sync dependencies (with self-heal) ──────────────────────────────────────
 
 cd /app/backend
@@ -82,4 +89,9 @@ fi
 
 PYTHONPATH=. exec uv run uvicorn app.gateway.app:app \
     --host 0.0.0.0 --port 8001 \
-    --reload --reload-include='*.yaml .env'
+    --reload \
+    --reload-include='*.yaml' \
+    --reload-include='.env' \
+    --reload-exclude=/app/backend/sandbox \
+    --reload-exclude="$DEER_FLOW_HOME" \
+    --reload-exclude=/app/backend/.deer-flow

scripts/serve.sh

@@ -285,9 +285,26 @@ else
     FRONTEND_CMD="env BETTER_AUTH_SECRET=$($PYTHON_BIN -c 'import secrets; print(secrets.token_hex(16))') pnpm run preview"
 fi
 
+# Runtime path defaults. Local `make dev` launches Gateway from `backend/`,
+# so pin DeerFlow-owned state to the expected backend runtime directory and
+# create it before uvicorn builds its reload exclude filter.
+if [ -z "$DEER_FLOW_PROJECT_ROOT" ]; then
+    export DEER_FLOW_PROJECT_ROOT="$REPO_ROOT"
+fi
+
+BACKEND_RUNTIME_HOME="$REPO_ROOT/backend/.deer-flow"
+if [ -z "$DEER_FLOW_HOME" ]; then
+    export DEER_FLOW_HOME="$BACKEND_RUNTIME_HOME"
+fi
+
+mkdir -p "$DEER_FLOW_HOME" "$BACKEND_RUNTIME_HOME"
+DEER_FLOW_HOME="$(cd "$DEER_FLOW_HOME" && pwd -P)"
+BACKEND_RUNTIME_HOME="$(cd "$BACKEND_RUNTIME_HOME" && pwd -P)"
+export DEER_FLOW_HOME
+
 # Extra flags for uvicorn
 if $DEV_MODE && ! $DAEMON_MODE; then
-    GATEWAY_EXTRA_FLAGS="--reload --reload-include='*.yaml' --reload-include='.env' --reload-exclude='*.pyc' --reload-exclude='__pycache__' --reload-exclude='sandbox/' --reload-exclude='.deer-flow/'"
+    GATEWAY_EXTRA_FLAGS="--reload --reload-include='*.yaml' --reload-include='.env' --reload-exclude='*.pyc' --reload-exclude='__pycache__' --reload-exclude='$REPO_ROOT/backend/sandbox' --reload-exclude='$DEER_FLOW_HOME' --reload-exclude='$BACKEND_RUNTIME_HOME'"
 else
     GATEWAY_EXTRA_FLAGS=""
 fi