Merge branch 'main' into copilot/fix-lint-frontend-job

fix(mcp): close stdio sessions on their owning loop to avoid cross-task cancel-scope error (#3379 ) (#3392 )
* fix(mcp): close stdio sessions on their owning loop to avoid cross-task cancel-scope error (#3379) Adopt an owner-task lifecycle for pooled MCP ClientSessions so each session is entered, initialized, and exited within a single asyncio task on its owning event loop. This eliminates the anyio "Attempted to exit cancel scope in a different task than it was entered in" RuntimeError that surfaced when stdio MCP tools were used via the sync tool wrapper (which spins up and tears down event loops across tasks). Also harden the pool lifecycle: - track in-flight session creation per (server, scope) to dedupe concurrent get_session() calls for the same key - make close_scope/close_server/close_all/close_all_sync cover both established entries and in-flight creations so sessions cannot be resurrected or leaked after close - handle cross-loop preemption of an in-flight creation by cancelling the stale owner task instead of only signalling it - define close_all_sync() semantics for a running loop on the current thread (signal-only, async completion) and route reset_mcp_tools_cache through a deterministic async close in that case * fix(mcp): avoid reset deadlock on running loop cache reset * fix(mcp): address session pool review feedback
2026-06-10 01:15:58 +00:00 · 2026-06-07 21:42:16 +08:00 · 2026-06-07 21:37:30 +08:00 · 2026-06-07 13:35:28 +00:00 · 2026-06-07 21:27:14 +08:00 · 2026-06-07 13:20:20 +00:00
173 changed files with 12914 additions and 2052 deletions
@@ -59,7 +59,7 @@ smoke-test/
 2. **Check pnpm** - Package manager
 3. **Check uv** - Python package manager
 4. **Check nginx** - Reverse proxy
-5. **Check required ports** - Confirm that ports 2026, 3000, 8001, and 2024 are not occupied
+5. **Check required ports** - Confirm that ports 2026, 3000, and 8001 are not occupied

 **Docker mode environment check** (if Docker is selected):
 1. **Check whether Docker is installed** - Run `docker --version`
@@ -93,17 +93,17 @@ smoke-test/
 ### Phase 5: Service Health Check

 **Local mode health check**:
-1. **Check process status** - Confirm that LangGraph, Gateway, Frontend, and Nginx processes are all running
+1. **Check process status** - Confirm that Gateway, Frontend, and Nginx processes are all running
 2. **Check frontend service** - Visit `http://localhost:2026` and verify that the page loads
 3. **Check API Gateway** - Verify the `http://localhost:2026/health` endpoint
-4. **Check LangGraph service** - Verify the availability of relevant endpoints
+4. **Check LangGraph-compatible API** - Verify the `/api/langgraph/*` route exposed by Gateway
 5. **Frontend route smoke check** - Run `bash .agent/skills/smoke-test/scripts/frontend_check.sh` to verify key routes under `/workspace`

 **Docker mode health check** (when using Docker):
 1. **Check container status** - Run `docker ps` and confirm that all containers are running
 2. **Check frontend service** - Visit `http://localhost:2026` and verify that the page loads
 3. **Check API Gateway** - Verify the `http://localhost:2026/health` endpoint
-4. **Check LangGraph service** - Verify the availability of relevant endpoints
+4. **Check LangGraph-compatible API** - Verify the `/api/langgraph/*` route exposed by Gateway
 5. **Frontend route smoke check** - Run `bash .agent/skills/smoke-test/scripts/frontend_check.sh` to verify key routes under `/workspace`

 ### Optional Functional Verification
@@ -135,7 +135,7 @@ smoke-test/

 The following warnings can appear during smoke testing and do not block a successful result:
 - Feishu/Lark SSL errors in Gateway logs (certificate verification failure) can be ignored if that channel is not enabled
- Warnings in LangGraph logs about missing methods in the custom checkpointer, such as `adelete_for_runs` or `aprune`, do not affect the core functionality
+- Warnings in Gateway logs about missing methods in the custom checkpointer, such as `adelete_for_runs` or `aprune`, do not affect the core functionality

 ## Key Tools

@@ -138,7 +138,6 @@ This document describes the detailed operating steps for each phase of the DeerF
   lsof -i :2026  # Main port
   lsof -i :3000  # Frontend
   lsof -i :8001  # Gateway
-   lsof -i :2024  # LangGraph
   ```

 **Success Criteria**: All ports are free, or they are occupied only by DeerFlow-related processes.
@@ -258,7 +257,7 @@ This document describes the detailed operating steps for each phase of the DeerF
 **Steps**:
 1. Run `make dev-daemon` (background mode)

-**Description**: This command starts all services (LangGraph, Gateway, Frontend, Nginx).
+**Description**: This command starts all services (Gateway embedded runtime, Frontend, Nginx).

 **Notes**:
 - `make dev` runs in the foreground and stops with Ctrl+C
@@ -272,7 +271,6 @@ This document describes the detailed operating steps for each phase of the DeerF
 **Steps**:
 1. Wait 90-120 seconds for all services to start completely
 2. You can monitor startup progress by checking these log files:
-   - `logs/langgraph.log`
   - `logs/gateway.log`
   - `logs/frontend.log`
   - `logs/nginx.log`
@@ -316,11 +314,10 @@ This document describes the detailed operating steps for each phase of the DeerF
 **Steps**:
 1. Run the following command to check processes:
   ```bash
-   ps aux | grep -E "(langgraph|uvicorn|next|nginx)" | grep -v grep
+   ps aux | grep -E "(uvicorn|next|nginx)" | grep -v grep
   ```

 **Success Criteria**: Confirm that the following processes are running:
- LangGraph (`langgraph dev`)
 - Gateway (`uvicorn app.gateway.app:app`)
 - Frontend (`next dev` or `next start`)
 - Nginx (`nginx`)
@@ -356,10 +353,11 @@ curl http://localhost:2026/health

 ---

-#### 5.1.4 Check LangGraph Service
+#### 5.1.4 Check LangGraph-compatible API

 **Steps**:
-1. Visit relevant LangGraph endpoints to verify availability
+1. Visit `http://localhost:2026/api/langgraph/assistants/lead_agent` to verify Gateway's LangGraph-compatible API route is reachable.
+2. A `401` response is acceptable when authentication is enabled and no session cookie is provided.

 ---

@@ -373,7 +371,6 @@ curl http://localhost:2026/health
   - `deer-flow-nginx`
   - `deer-flow-frontend`
   - `deer-flow-gateway`
-   - `deer-flow-langgraph` (if not in gateway mode)

 ---

@@ -406,10 +403,11 @@ curl http://localhost:2026/health

 ---

-#### 5.2.4 Check LangGraph Service
+#### 5.2.4 Check LangGraph-compatible API

 **Steps**:
-1. Visit relevant LangGraph endpoints to verify availability
+1. Visit `http://localhost:2026/api/langgraph/assistants/lead_agent` to verify Gateway's LangGraph-compatible API route is reachable.
+2. A `401` response is acceptable when authentication is enabled and no session cookie is provided.

 ---

@@ -254,7 +254,6 @@ Processes exit quickly after running `make dev-daemon`.
 **Solutions**:
 1. Check log files:
   ```bash
-   tail -f logs/langgraph.log
   tail -f logs/gateway.log
   tail -f logs/frontend.log
   tail -f logs/nginx.log
@@ -367,24 +366,7 @@ Errors appear in `gateway.log`.
   uv sync
   ```

-4. Confirm that the LangGraph service is running normally (if not in gateway mode)
-
---
-
-### Issue: LangGraph Fails to Start
-
-**Symptoms**:
-Errors appear in `langgraph.log`.
-
-**Solutions**:
-1. Check LangGraph logs:
-   ```bash
-   tail -f logs/langgraph.log
-   ```
-
-2. Check config.yaml
-3. Check whether Python dependencies are complete
-4. Confirm that port 2024 is not occupied
+4. Confirm that the Gateway process is running normally.

 ---

@@ -519,7 +501,7 @@ Accessing `/health` returns an error or times out.

 2. Confirm that config.yaml exists and has valid formatting
 3. Check whether Python dependencies are complete
-4. Confirm that the LangGraph service is running normally
+4. Confirm that the Gateway process is running normally.

 **Solutions** (Docker mode):
 1. Check gateway container logs:
@@ -529,7 +511,7 @@ Accessing `/health` returns an error or times out.

 2. Confirm that config.yaml is mounted correctly
 3. Check whether Python dependencies are complete
-4. Confirm that the LangGraph service is running normally
+4. Confirm that the Gateway process is running normally.

 ---

@@ -539,7 +521,7 @@ Accessing `/health` returns an error or times out.

 #### View All Service Processes
 ```bash
-ps aux | grep -E "(langgraph|uvicorn|next|nginx)" | grep -v grep
+ps aux | grep -E "(uvicorn|next|nginx)" | grep -v grep
 ```

 #### View Service Logs
@@ -548,7 +530,6 @@ ps aux | grep -E "(langgraph|uvicorn|next|nginx)" | grep -v grep
 tail -f logs/*.log

 # View specific service logs
-tail -f logs/langgraph.log
 tail -f logs/gateway.log
 tail -f logs/frontend.log
 tail -f logs/nginx.log
@@ -65,7 +65,7 @@ if ! command -v lsof >/dev/null 2>&1; then
    echo "  Install lsof and rerun this check"
    all_passed=false
 else
-    for port in 2026 3000 8001 2024; do
+    for port in 2026 3000 8001; do
        if lsof -i :$port >/dev/null 2>&1; then
            echo "⚠  Port $port is already in use:"
            lsof -i :$port | head -2
@@ -54,7 +54,6 @@ echo "=========================================="
 echo ""
 echo "🌐 Access URL: http://localhost:2026"
 echo "📋 View logs:"
-echo "   - logs/langgraph.log"
 echo "   - logs/gateway.log"
 echo "   - logs/frontend.log"
 echo "   - logs/nginx.log"
@@ -76,12 +76,11 @@ if [ "$mode" = "docker" ]; then
        all_passed=false
    fi
 else
-    summary_hint="logs/{langgraph,gateway,frontend,nginx}.log"
+    summary_hint="logs/{gateway,frontend,nginx}.log"
    print_step "1. Checking local service ports..."
    check_listen_port "Nginx" 2026
    check_listen_port "Frontend" 3000
    check_listen_port "Gateway" 8001
-    check_listen_port "LangGraph" 2024
 fi
 echo ""

@@ -104,8 +103,8 @@ else
 fi
 echo ""

-echo "5. Checking LangGraph service..."
-check_http_status "LangGraph service" "http://localhost:2024/" "200|301|302|307|308|404"
+echo "5. Checking LangGraph-compatible Gateway API..."
+check_http_status "LangGraph-compatible Gateway API" "http://localhost:2026/api/langgraph/assistants/lead_agent" "200|401"
 echo ""

 echo "=========================================="
@@ -78,7 +78,7 @@
 - [x] Container status - {{status_containers}}
 - [x] Frontend service - {{status_frontend}}
 - [x] API Gateway - {{status_api_gateway}}
- [x] LangGraph service - {{status_langgraph}}
+- [x] LangGraph-compatible Gateway API - {{status_langgraph}}

 **Phase Status**: {{stage5_status}}

@@ -147,7 +147,6 @@ Commit Message: {{git_commit_message}}
 | deer-flow-nginx | {{nginx_status}} | {{nginx_uptime}} |
 | deer-flow-frontend | {{frontend_status}} | {{frontend_uptime}} |
 | deer-flow-gateway | {{gateway_status}} | {{gateway_uptime}} |
-| deer-flow-langgraph | {{langgraph_status}} | {{langgraph_uptime}} |

 ---

@@ -80,7 +80,7 @@
 - [x] Process status - {{status_processes}}
 - [x] Frontend service - {{status_frontend}}
 - [x] API Gateway - {{status_api_gateway}}
- [x] LangGraph service - {{status_langgraph}}
+- [x] LangGraph-compatible Gateway API - {{status_langgraph}}

 **Phase Status**: {{stage5_status}}

@@ -152,7 +152,7 @@ Commit Message: {{git_commit_message}}
 | Nginx | {{nginx_status}} | {{nginx_endpoint}} |
 | Frontend | {{frontend_status}} | {{frontend_endpoint}} |
 | Gateway | {{gateway_status}} | {{gateway_endpoint}} |
-| LangGraph | {{langgraph_status}} | {{langgraph_endpoint}} |
+| Gateway LangGraph API | {{langgraph_status}} | {{langgraph_endpoint}} |

 ---

@@ -166,7 +166,7 @@ Commit Message: {{git_commit_message}}

 ### If the Test Fails
 1. [ ] Review references/troubleshooting.md for common solutions
-2. [ ] Check local logs: `logs/{langgraph,gateway,frontend,nginx}.log`
+2. [ ] Check local logs: `logs/{gateway,frontend,nginx}.log`
 3. [ ] Verify configuration file format and content
 4. [ ] If needed, fully reset the environment: `make stop && make clean && make install && make dev-daemon`

@@ -0,0 +1,159 @@
+name: 🐛 Bug report
+description: Report something that isn't working so maintainers can reproduce and fix it.
+title: "[bug] "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug. A clear, reproducible report is the
+        single biggest factor in how fast it gets fixed.
+
+        Please fill in every required field — especially **reproduction steps** and **logs**.
+
+  - type: checkboxes
+    id: preflight
+    attributes:
+      label: Before you start
+      options:
+        - label: I searched [existing issues](https://github.com/bytedance/deer-flow/issues?q=is%3Aissue) and this is not a duplicate.
+          required: true
+        - label: I can reproduce this on the latest `main`.
+          required: false
+
+  - type: input
+    id: summary
+    attributes:
+      label: Problem summary
+      description: One sentence describing the bug.
+      placeholder: e.g. make dev fails to start the gateway service
+    validations:
+      required: true
+
+  - type: dropdown
+    id: areas
+    attributes:
+      label: Affected area(s)
+      description: Which part of DeerFlow does this touch? Select all that apply.
+      multiple: true
+      options:
+        - Frontend (UI / Next.js)
+        - Backend API (gateway / endpoints / SSE)
+        - Agents / LangGraph (graph, prompts, langgraph.json)
+        - Sandbox / Docker
+        - Skills
+        - MCP
+        - Config / setup (make, config.yaml, env)
+        - Docs
+        - Not sure
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: What happened?
+      description: The actual behavior. Include the key error lines verbatim.
+      placeholder: When I do X, I expected Y but I got Z.
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      placeholder: What did you expect to happen instead?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: Exact commands and sequence. Minimal steps that reliably reproduce the problem.
+      placeholder: |
+        1. make check
+        2. make install
+        3. make dev
+        4. ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant logs
+      description: Paste key lines from logs (for example `logs/gateway.log`, `logs/frontend.log`). Redact secrets.
+      render: shell
+    validations:
+      required: true
+
+  - type: dropdown
+    id: run_mode
+    attributes:
+      label: How are you running DeerFlow?
+      options:
+        - Local (make dev)
+        - Docker (make docker-start)
+        - CI
+        - Other
+    validations:
+      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options:
+        - macOS
+        - Linux
+        - Windows
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: platform_details
+    attributes:
+      label: Platform details
+      description: Architecture and shell, if relevant.
+      placeholder: e.g. arm64, zsh
+
+  - type: input
+    id: python_version
+    attributes:
+      label: Python version
+      placeholder: e.g. Python 3.12.9
+
+  - type: input
+    id: node_version
+    attributes:
+      label: Node.js version
+      placeholder: e.g. v22.11.0
+
+  - type: input
+    id: pnpm_version
+    attributes:
+      label: pnpm version
+      placeholder: e.g. 10.26.2
+
+  - type: input
+    id: uv_version
+    attributes:
+      label: uv version
+      placeholder: e.g. 0.7.20
+
+  - type: textarea
+    id: git_info
+    attributes:
+      label: Git state
+      description: Output of `git branch --show-current` and the latest commit SHA.
+      placeholder: |
+        branch: feature/my-branch
+        commit: abcdef1
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: Screenshots, related issues, config snippets (redacted), or anything else that helps triage.
@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 💬 Questions & usage help
+    url: https://github.com/bytedance/deer-flow/discussions/categories/q-a
+    about: "How do I use X? Why does Y behave like that? Ask in Discussions — it gets answered faster and stays searchable."
+  - name: 💡 Ideas & proposals
+    url: https://github.com/bytedance/deer-flow/discussions/categories/ideas
+    about: Have a half-formed idea? Float it in Discussions before opening a formal feature request.
+  - name: 🔒 Report a security vulnerability
+    url: https://github.com/bytedance/deer-flow/security/policy
+    about: Do not open a public issue for security problems. Follow the security policy instead.
@@ -0,0 +1,67 @@
+name: 💡 Feature request
+description: Propose a new capability or an improvement to an existing one.
+title: "[feat] "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the suggestion. For non-trivial features, please open a
+        [Discussion](https://github.com/bytedance/deer-flow/discussions/categories/ideas)
+        first to align on scope before writing code.
+
+  - type: checkboxes
+    id: preflight
+    attributes:
+      label: Before you start
+      options:
+        - label: I searched [existing issues](https://github.com/bytedance/deer-flow/issues?q=is%3Aissue) and this is not a duplicate.
+          required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / motivation
+      description: What problem does this solve? What is painful today, or what does it unblock?
+      placeholder: "I'm always frustrated when ..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: Describe the change from a user's / caller's perspective.
+    validations:
+      required: true
+
+  - type: dropdown
+    id: areas
+    attributes:
+      label: Affected area(s)
+      description: Which part of DeerFlow would this touch? Select all that apply.
+      multiple: true
+      options:
+        - Frontend (UI / Next.js)
+        - Backend API (gateway / endpoints / SSE)
+        - Agents / LangGraph (graph, prompts, langgraph.json)
+        - Sandbox / Docker
+        - Skills
+        - MCP
+        - Config / setup
+        - Docs
+        - Not sure
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches you weighed and why you discarded them.
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: Mockups, links, related issues, or anything else that helps.
@@ -1,128 +0,0 @@
-name: Runtime Information
-description: Report runtime/environment details to help reproduce an issue.
-title: "[runtime] "
-labels:
-  - needs-triage
-body:
-  - type: markdown
-    attributes:
-      value: |
-        Thanks for sharing runtime details.
-        Complete this form so maintainers can quickly reproduce and diagnose the problem.
-
-  - type: input
-    id: summary
-    attributes:
-      label: Problem summary
-      description: Short summary of the issue.
-      placeholder: e.g. make dev fails to start gateway service
-    validations:
-      required: true
-
-  - type: textarea
-    id: expected
-    attributes:
-      label: Expected behavior
-      placeholder: What did you expect to happen?
-    validations:
-      required: true
-
-  - type: textarea
-    id: actual
-    attributes:
-      label: Actual behavior
-      placeholder: What happened instead? Include key error lines.
-    validations:
-      required: true
-
-  - type: dropdown
-    id: os
-    attributes:
-      label: Operating system
-      options:
-        - macOS
-        - Linux
-        - Windows
-        - Other
-    validations:
-      required: true
-
-  - type: input
-    id: platform_details
-    attributes:
-      label: Platform details
-      description: Add architecture and shell if relevant.
-      placeholder: e.g. arm64, zsh
-
-  - type: input
-    id: python_version
-    attributes:
-      label: Python version
-      placeholder: e.g. Python 3.12.9
-
-  - type: input
-    id: node_version
-    attributes:
-      label: Node.js version
-      placeholder: e.g. v23.11.0
-
-  - type: input
-    id: pnpm_version
-    attributes:
-      label: pnpm version
-      placeholder: e.g. 10.26.2
-
-  - type: input
-    id: uv_version
-    attributes:
-      label: uv version
-      placeholder: e.g. 0.7.20
-
-  - type: dropdown
-    id: run_mode
-    attributes:
-      label: How are you running DeerFlow?
-      options:
-        - Local (make dev)
-        - Docker (make docker-dev)
-        - CI
-        - Other
-    validations:
-      required: true
-
-  - type: textarea
-    id: reproduce
-    attributes:
-      label: Reproduction steps
-      description: Provide exact commands and sequence.
-      placeholder: |
-        1. make check
-        2. make install
-        3. make dev
-        4. ...
-    validations:
-      required: true
-
-  - type: textarea
-    id: logs
-    attributes:
-      label: Relevant logs
-      description: Paste key lines from logs (for example logs/gateway.log, logs/frontend.log).
-      render: shell
-    validations:
-      required: true
-
-  - type: textarea
-    id: git_info
-    attributes:
-      label: Git state
-      description: Share output of git branch and latest commit SHA.
-      placeholder: |
-        branch: feature/my-branch
-        commit: abcdef1
-
-  - type: textarea
-    id: additional
-    attributes:
-      label: Additional context
-      description: Add anything else that might help triage.
@@ -0,0 +1,72 @@
+# Path-based PR auto-labeling config for actions/labeler@v5.
+# Each key is a label (must exist — see .github/labels.yml); the globs decide
+# when it is applied. A PR can match several areas, which is expected.
+
+"area:frontend":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "frontend/**"
+
+"area:backend":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "backend/app/**"
+          - "backend/packages/harness/deerflow/runtime/**"
+          - "backend/packages/harness/deerflow/persistence/**"
+          - "backend/packages/harness/deerflow/config/**"
+          - "backend/packages/harness/deerflow/tools/**"
+          - "backend/packages/harness/deerflow/guardrails/**"
+          - "backend/packages/harness/deerflow/tracing/**"
+          - "backend/packages/harness/deerflow/models/**"
+          - "backend/packages/harness/deerflow/utils/**"
+          - "backend/packages/harness/deerflow/uploads/**"
+
+"area:agents":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "backend/packages/harness/deerflow/agents/**"
+          - "backend/packages/harness/deerflow/subagents/**"
+          - "backend/packages/harness/deerflow/reflection/**"
+          - "backend/langgraph.json"
+          - "backend/**/prompts/**"
+
+"area:sandbox":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "docker/**"
+          - "backend/packages/harness/deerflow/sandbox/**"
+          - "backend/Dockerfile"
+          - "frontend/Dockerfile"
+
+"area:skills":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "skills/**"
+          - "backend/packages/harness/deerflow/skills/**"
+          - "frontend/src/core/skills/**"
+
+"area:mcp":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "backend/packages/harness/deerflow/mcp/**"
+          - "frontend/src/core/mcp/**"
+
+"area:ci":
+  - changed-files:
+      - any-glob-to-any-file:
+          - ".github/**"
+          - "scripts/**"
+
+"area:docs":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "docs/**"
+          - "**/*.md"
+
+"area:deps":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "backend/pyproject.toml"
+          - "backend/uv.lock"
+          - "frontend/package.json"
+          - "frontend/pnpm-lock.yaml"
@@ -0,0 +1,119 @@
+# Declarative label source of truth for DeerFlow.
+#
+# This file is the single source of truth for repository labels used by the
+# auto-labeling workflows (.github/workflows/pr-labeler.yml, pr-triage.yml,
+# issue-triage.yml). Auto-labelers can only apply labels that already exist,
+# so every label referenced by a workflow MUST be declared here.
+#
+# Apply with:  uv run --with pyyaml python scripts/sync_labels.py [--repo OWNER/NAME]
+# CI keeps it in sync via .github/workflows/label-sync.yml (runs on changes here).
+#
+# Sync is additive/update-only: it creates or updates the labels listed below
+# and never deletes labels that are not listed.
+#
+# Color = 6-digit hex without the leading '#'.
+
+labels:
+  # ── Type ─────────────────────────────────────────────────────────────────
+  # Mostly GitHub defaults; declared here so colors/descriptions stay stable
+  # and so issue templates can rely on them existing.
+  - name: bug
+    color: d73a4a
+    description: Something isn't working
+  - name: enhancement
+    color: a2eeef
+    description: New feature or request
+  - name: documentation
+    color: 0075ca
+    description: Improvements or additions to documentation
+  - name: question
+    color: d876e3
+    description: Further information is requested
+
+  # ── Area (auto, by changed paths — see .github/labeler.yml) ───────────────
+  # Mirrors the "Surface area" section of the pull request template.
+  - name: "area:frontend"
+    color: c5def5
+    description: Next.js frontend under frontend/
+  - name: "area:backend"
+    color: c5def5
+    description: Gateway / runtime / core backend under backend/
+  - name: "area:agents"
+    color: c5def5
+    description: Agents, subagents, graph wiring, prompts, langgraph.json
+  - name: "area:sandbox"
+    color: c5def5
+    description: Sandboxed execution and docker/
+  - name: "area:skills"
+    color: c5def5
+    description: Skills under skills/ or the skills harness
+  - name: "area:mcp"
+    color: c5def5
+    description: Model Context Protocol integration
+  - name: "area:ci"
+    color: c5def5
+    description: GitHub Actions, CI config, repo tooling
+  - name: "area:docs"
+    color: c5def5
+    description: Documentation and Markdown only
+  - name: "area:deps"
+    color: c5def5
+    description: Dependency manifests / lockfiles
+
+  # ── Size (auto, by additions + deletions — see pr-triage.yml) ─────────────
+  - name: "size/XS"
+    color: "009900"
+    description: PR changes < 20 lines
+  - name: "size/S"
+    color: 77bb00
+    description: PR changes 20-100 lines
+  - name: "size/M"
+    color: eebb00
+    description: PR changes 100-300 lines
+  - name: "size/L"
+    color: ee9900
+    description: PR changes 300-700 lines
+  - name: "size/XL"
+    color: ee5500
+    description: PR changes 700+ lines
+
+  # ── Risk (auto, by changed paths — see pr-triage.yml) ─────────────────────
+  - name: "risk:low"
+    color: 0e8a16
+    description: "Low risk: docs / i18n / assets only"
+  - name: "risk:medium"
+    color: fbca04
+    description: "Medium risk: regular code changes"
+  - name: "risk:high"
+    color: b60205
+    description: "High risk: backend API, agents, sandbox, auth, deps, CI"
+
+  # ── Priority (manual) ─────────────────────────────────────────────────────
+  - name: P0
+    color: b60205
+    description: Critical priority
+  - name: P1
+    color: d93f0b
+    description: Major priority
+  - name: P2
+    color: e99695
+    description: Normal priority
+
+  # ── Status (auto + manual) ────────────────────────────────────────────────
+  - name: needs-triage
+    color: fef2c0
+    description: Awaiting maintainer triage
+  - name: needs-validation
+    color: d4c5f9
+    description: Touches front/back contract surface; needs real-path validation
+  - name: skip-validation
+    color: cccccc
+    description: "Maintainer override: do not auto-add needs-validation on this PR"
+  - name: reviewing
+    color: 5319e7
+    description: A maintainer is reviewing this PR
+
+  # ── Contributor ───────────────────────────────────────────────────────────
+  - name: first-time-contributor
+    color: c2e0c6
+    description: First contribution to this repository — be welcoming
@@ -59,3 +59,17 @@ Fixes #
       Frontend:  cd frontend && pnpm format && pnpm lint && pnpm typecheck && BETTER_AUTH_SECRET=local-dev-secret pnpm build && make test
       Frontend E2E (if you touched frontend/): cd frontend && make test-e2e -->

+
+## AI assistance
+
+<!-- DeerFlow is an AI project — most PRs here use AI coding tools, and that's
+     welcome. Disclosing it just helps reviewers calibrate how closely to read the
+     diff. Please fill all three; don't delete the section. -->
+
+**Tool(s) used:** <!-- e.g. Claude Code, Cursor, GitHub Copilot, Codex, Windsurf, or "none" -->
+
+**How you used it:** <!-- e.g. "generated the module from a spec", "autocomplete only",
+     "AI wrote tests, I wrote the impl". A prompt or conversation link is great too. -->
+
+- [ ] I've read and understand every line of this change and take responsibility for it — it's not unreviewed AI output.
+
@@ -0,0 +1,44 @@
+name: Issue Triage
+
+# Ensures every newly opened issue carries `needs-triage`, even blank or
+# API-created ones that bypass the issue templates. Creates the label if it is
+# somehow missing, so the workflow is self-healing.
+
+on:
+  issues:
+    types: [opened]
+
+permissions:
+  issues: write
+
+jobs:
+  needs-triage:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Add needs-triage label
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const { owner, repo } = context.repo;
+            const issue_number = context.payload.issue.number;
+
+            const current = (context.payload.issue.labels || []).map(l => l.name);
+            if (current.includes('needs-triage')) {
+              core.info('Issue already has needs-triage; nothing to do.');
+              return;
+            }
+
+            // Self-heal: create the label if it does not exist yet.
+            try {
+              await github.rest.issues.createLabel({
+                owner, repo, name: 'needs-triage', color: 'fef2c0',
+                description: 'Awaiting maintainer triage',
+              });
+            } catch (e) {
+              if (e.status !== 422) throw e; // 422 = already exists
+            }
+
+            await github.rest.issues.addLabels({
+              owner, repo, issue_number, labels: ['needs-triage'],
+            });
+            core.info(`Added needs-triage to #${issue_number}.`);
@@ -0,0 +1,38 @@
+name: Label Sync
+
+# Keeps repository labels in sync with the declarative source of truth
+# (.github/labels.yml). Runs whenever that file changes on main, and can be
+# triggered manually. Additive/update-only — never deletes labels.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - ".github/labels.yml"
+      - "scripts/sync_labels.py"
+      - ".github/workflows/label-sync.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+concurrency:
+  group: label-sync
+  cancel-in-progress: false
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Sync labels
+        run: uv run --with pyyaml python scripts/sync_labels.py
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_REPO: ${{ github.repository }}
@@ -0,0 +1,28 @@
+name: PR Labeler
+
+# Applies area:* labels based on which files a PR changes (see .github/labeler.yml).
+# Uses pull_request_target so it also works on fork PRs. SAFE: actions/labeler
+# only reads the changed-file list via the API — it never checks out or runs PR code.
+
+on:
+  pull_request_target:
+    types: [opened, synchronize, reopened, ready_for_review]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: pr-labeler-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  label:
+    if: github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    steps:
+      - name: Apply area labels
+        uses: actions/labeler@v5
+        with:
+          configuration-path: .github/labeler.yml
+          sync-labels: true
@@ -0,0 +1,164 @@
+name: PR Triage
+
+# Two responsibilities, both pure-metadata (no PR code is checked out or run):
+#   1. On open/sync: apply size/* + risk:* labels, and needs-validation when the
+#      PR touches the front/back contract surface (backend API, SSE, agents, or
+#      the frontend streaming client). A `skip-validation` label opts out.
+#   2. On maintainer review: apply the `reviewing` label.
+#
+# All labels are managed within their own namespace — labels outside size/*,
+# risk:*, needs-validation and reviewing are never touched here.
+
+on:
+  pull_request_target:
+    types: [opened, synchronize, reopened, ready_for_review]
+  pull_request_review:
+    types: [submitted]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: pr-triage-${{ github.event.pull_request.number }}
+  cancel-in-progress: false
+
+jobs:
+  size-and-risk:
+    if: github.event_name == 'pull_request_target' && github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    steps:
+      - name: Label size, risk and validation need
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const pr = context.payload.pull_request;
+            const { owner, repo } = context.repo;
+            const prNumber = pr.number;
+
+            // ---- size, from additions + deletions ----
+            const churn = (pr.additions || 0) + (pr.deletions || 0);
+            const sizeLabel =
+              churn < 20 ? 'size/XS' :
+              churn < 100 ? 'size/S' :
+              churn < 300 ? 'size/M' :
+              churn < 700 ? 'size/L' : 'size/XL';
+
+            // ---- changed paths ----
+            const files = await github.paginate(github.rest.pulls.listFiles, {
+              owner, repo, pull_number: prNumber, per_page: 100,
+            });
+            const paths = files.map(f => f.filename);
+
+            const matches = (re) => paths.some(p => re.test(p));
+
+            const docsOnly = paths.length > 0 && paths.every(p =>
+              /\.(md|mdx|txt)$/i.test(p) || p.startsWith('docs/') ||
+              /\.(png|jpe?g|gif|svg|webp|ico)$/i.test(p));
+
+            const highRisk = matches(
+              /^backend\/app\/gateway\//) || matches(
+              /^backend\/packages\/harness\/deerflow\/(agents|subagents|sandbox)\//) || matches(
+              /(^|\/)langgraph\.json$/) || matches(
+              /(^|\/)(auth|authz|security)/i) || matches(
+              /(pyproject\.toml|uv\.lock|package\.json|pnpm-lock\.yaml)$/) || matches(
+              /^docker\//) || matches(
+              /^\.github\/workflows\//);
+
+            const riskLabel = docsOnly ? 'risk:low' : (highRisk ? 'risk:high' : 'risk:medium');
+
+            // needs-validation: front/back contract surface
+            const contractSurface =
+              matches(/^backend\/app\/gateway\//) ||
+              matches(/^backend\/packages\/harness\/deerflow\/(agents|subagents)\//) ||
+              matches(/(^|\/)langgraph\.json$/) ||
+              matches(/^frontend\/src\/core\/(api|threads|messages)\//);
+
+            const current = (pr.labels || []).map(l => l.name);
+            const hasSkip = current.includes('skip-validation');
+
+            const desired = [sizeLabel, riskLabel];
+            if (contractSurface && !hasSkip) desired.push('needs-validation');
+
+            const managed = (name) =>
+              name.startsWith('size/') || name.startsWith('risk:') || name === 'needs-validation';
+
+            const toRemove = current.filter(l => managed(l) && !desired.includes(l));
+            const toAdd = desired.filter(l => !current.includes(l));
+
+            for (const name of toRemove) {
+              try {
+                await github.rest.issues.removeLabel({ owner, repo, issue_number: prNumber, name });
+              } catch (e) {
+                if (e.status !== 404) throw e;
+              }
+            }
+            if (toAdd.length) {
+              await github.rest.issues.addLabels({ owner, repo, issue_number: prNumber, labels: toAdd });
+            }
+            core.info(`size=${sizeLabel} risk=${riskLabel} churn=${churn} ` +
+              `validation=${desired.includes('needs-validation')} ` +
+              `(+${toAdd.join(',') || '-'} / -${toRemove.join(',') || '-'})`);
+
+  first-time:
+    if: github.event_name == 'pull_request_target' && github.event.action == 'opened'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Label first-time contributors
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const pr = context.payload.pull_request;
+            const { owner, repo } = context.repo;
+            const assoc = pr.author_association;
+            const isBot = pr.user.type === 'Bot';
+            core.info(`author=${pr.user.login} association=${assoc} bot=${isBot}`);
+
+            // FIRST_TIME_CONTRIBUTOR = no prior merged commit to this repo;
+            // FIRST_TIMER = no prior commit anywhere on GitHub. Either counts.
+            if (isBot || !['FIRST_TIME_CONTRIBUTOR', 'FIRST_TIMER'].includes(assoc)) {
+              core.info('Not a first-time contributor; skipping.');
+              return;
+            }
+            await github.rest.issues.addLabels({
+              owner, repo, issue_number: pr.number, labels: ['first-time-contributor'],
+            });
+            core.info(`Added first-time-contributor to #${pr.number}.`);
+
+  reviewing:
+    if: github.event_name == 'pull_request_review'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Add reviewing label for maintainer reviews
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const { owner, repo } = context.repo;
+            const prNumber = context.payload.pull_request.number;
+            const reviewer = context.payload.review.user.login;
+
+            const { data: perm } = await github.rest.repos.getCollaboratorPermissionLevel({
+              owner, repo, username: reviewer,
+            });
+            if (!['admin', 'write', 'maintain'].includes(perm.permission)) {
+              core.info(`Reviewer ${reviewer} (${perm.permission}) is not a maintainer; skipping.`);
+              return;
+            }
+
+            const { data: labels } = await github.rest.issues.listLabelsOnIssue({
+              owner, repo, issue_number: prNumber,
+            });
+            if (labels.some(l => l.name === 'reviewing')) {
+              core.info('Already labeled reviewing; skipping.');
+              return;
+            }
+            try {
+              await github.rest.issues.addLabels({
+                owner, repo, issue_number: prNumber, labels: ['reviewing'],
+              });
+              core.info(`Added "reviewing" (reviewer ${reviewer}).`);
+            } catch (e) {
+              // 403 is expected for review events on some fork PR contexts.
+              if (e.status === 403) core.info('No permission to label (expected on some fork PRs).');
+              else throw e;
+            }
@@ -287,6 +287,21 @@ Nginx (port 2026) ← Unified entry point
   git push origin feature/your-feature-name
   ```

+## AI assistance disclosure
+
+DeerFlow is an AI project and we welcome AI-assisted contributions. To help
+reviewers calibrate how closely to read a change, **every pull request must
+complete the "AI assistance" section of the
+[PR template](.github/pull_request_template.md)**:
+
+- which tool(s) you used (or `none`),
+- how you used them, and
+- a confirmation that a human has read, understands, and takes responsibility
+  for the change.
+
+Please don't delete the section. PRs that ignore it may be asked to fill it in
+before review.
+
 ## Testing

 ```bash
@@ -89,36 +89,7 @@ install:

 # Pre-pull sandbox Docker image (optional but recommended)
 setup-sandbox:
-	@echo "=========================================="
-	@echo "  Pre-pulling Sandbox Container Image"
-	@echo "=========================================="
-	@echo ""
-	@IMAGE=$$(grep -A 20 "# sandbox:" config.yaml 2>/dev/null | grep "image:" | awk '{print $$2}' | head -1); \
-	if [ -z "$$IMAGE" ]; then \
-		IMAGE="enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest"; \
-		echo "Using default image: $$IMAGE"; \
-	else \
-		echo "Using configured image: $$IMAGE"; \
-	fi; \
-	echo ""; \
-	if command -v container >/dev/null 2>&1 && [ "$$(uname)" = "Darwin" ]; then \
-		echo "Detected Apple Container on macOS, pulling image..."; \
-		container image pull "$$IMAGE" || echo "⚠ Apple Container pull failed, will try Docker"; \
-	fi; \
-	if command -v docker >/dev/null 2>&1; then \
-		echo "Pulling image using Docker..."; \
-		if docker pull "$$IMAGE"; then \
-			echo ""; \
-			echo "✓ Sandbox image pulled successfully"; \
-		else \
-			echo ""; \
-			echo "⚠ Failed to pull sandbox image (this is OK for local sandbox mode)"; \
-		fi; \
-	else \
-		echo "✗ Neither Docker nor Apple Container is available"; \
-		echo "  Please install Docker: https://docs.docker.com/get-docker/"; \
-		exit 1; \
-	fi
+	@$(RUN_WITH_GIT_BASH) ./scripts/setup-sandbox.sh

 # Start all services in development mode (with hot-reloading)
 dev:
@@ -148,7 +119,6 @@ stop:
 clean: stop
 	@echo "Cleaning up..."
 	@-rm -rf backend/.deer-flow 2>/dev/null || true
-	@-rm -rf backend/.langgraph_api 2>/dev/null || true
 	@-rm -rf logs/*.log 2>/dev/null || true
 	@echo "✓ Cleanup complete"

@@ -122,10 +122,14 @@ Blocking-IO runtime gate (`tests/blocking_io/`):
  `tests/support/detectors/blocking_io_runtime.py`). Any sync blocking IO
  call whose stack passes through DeerFlow business code while running on
  the asyncio event loop raises `BlockingError` and fails the test.
- Two regression anchors live there: `test_skills_load.py` (locks the
+- Regression anchors live there: `test_skills_load.py` (locks the
  `asyncio.to_thread` offload around `LocalSkillStorage.load_skills`, fix
-  for #1917) and `test_sqlite_lifespan.py` (locks the offload around
-  SQLite path resolution plus `ensure_sqlite_parent_dir`, fix for #1912).
+  for #1917); `test_sqlite_lifespan.py` (locks the offload around
+  SQLite path resolution plus `ensure_sqlite_parent_dir`, fix for #1912);
+  `test_jsonl_run_event_store.py` (locks `JsonlRunEventStore`'s async
+  API offloading its file IO via `asyncio.to_thread`, fix #3084); and
+  `test_uploads_middleware.py` (locks `UploadsMiddleware.abefore_agent`
+  offloading the uploads-directory scan off the event loop).
 - `test_gate_smoke.py` is a meta-test asserting the gate actually catches
  unoffloaded blocking IO and that the `@pytest.mark.allow_blocking_io`
  opt-out works.
@@ -204,7 +208,7 @@ Lead-agent middlewares are assembled in strict append order across `packages/har
 12. **TitleMiddleware** - Auto-generates thread title after first complete exchange and normalizes structured message content before prompting the title model
 13. **MemoryMiddleware** - Queues conversations for async memory update (filters to user + final AI responses)
 14. **ViewImageMiddleware** - Injects base64 image data before LLM call (conditional on vision support)
-15. **DeferredToolFilterMiddleware** - Hides deferred tool schemas from the bound model until tool search is enabled (optional)
+15. **DeferredToolFilterMiddleware** - Hides deferred (MCP) tool schemas from the bound model using a build-time deferred-name set + catalog hash, reading per-thread promotions from `ThreadState.promoted` (hash-scoped, no ContextVar); a tool becomes bound on subsequent turns after `tool_search` returns its schema (optional, if `tool_search.enabled`)
 16. **SubagentLimitMiddleware** - Truncates excess `task` tool calls from model response to enforce `MAX_CONCURRENT_SUBAGENTS` limit (optional, if `subagent_enabled`)
 17. **LoopDetectionMiddleware** - Detects repeated tool-call loops; hard-stop responses clear both structured `tool_calls` and raw provider tool-call metadata before forcing a final text answer
 18. **ClarificationMiddleware** - Intercepts `ask_clarification` tool calls, interrupts via `Command(goto=END)` (must be last)
@@ -219,17 +223,9 @@ Setup: Copy `config.example.yaml` to `config.yaml` in the **project root** direc

 **Config Caching**: `get_app_config()` caches the parsed config, but automatically reloads it when the resolved config path changes or the file's mtime increases. This keeps Gateway and LangGraph reads aligned with `config.yaml` edits without requiring a manual process restart.

-**Config Hot-Reload Boundary**: Gateway dependencies route through `get_app_config()` on every request, so per-run fields like `models[*].max_tokens`, `summarization.*`, `title.*`, `memory.*`, `subagents.*`, `tools[*]`, and the agent system prompt pick up `config.yaml` edits on the next message. `AppConfig` is intentionally **not** cached on `app.state` — `lifespan()` keeps a local `startup_config` variable for one-shot bootstrap work (logging level, channels, `langgraph_runtime` engines) and passes it explicitly to `langgraph_runtime(app, startup_config)`. Infrastructure fields are **restart-required**:
+**Config Hot-Reload Boundary**: Gateway dependencies route through `get_app_config()` on every request, so per-run fields like `models[*].max_tokens`, `summarization.*`, `title.*`, `memory.*`, `subagents.*`, `tools[*]`, and the agent system prompt pick up `config.yaml` edits on the next message. `AppConfig` is intentionally **not** cached on `app.state` — `lifespan()` keeps a local `startup_config` variable for one-shot bootstrap work and passes it to `langgraph_runtime(app, startup_config)`.

-| Field | Why a restart is required |
-|---|---|
-| `database.*` | `init_engine_from_config()` runs once during `langgraph_runtime()` startup; the SQLAlchemy engine holds the connection pool. |
-| `checkpointer.*` (including SQLite WAL/journal settings) | `make_checkpointer()` binds the persistent checkpointer once at startup. |
-| `run_events.*` | `make_run_event_store()` selects memory- vs. SQL-backed implementation at startup. |
-| `stream_bridge.*` | `make_stream_bridge()` constructs the bridge object once. |
-| `sandbox.use` | `get_sandbox_provider()` caches the provider singleton (`_default_sandbox_provider`); a new class path takes effect only on next process start. |
-| `log_level` | `apply_logging_level()` is called only in `app.py` startup; it mutates the root logger's level, and `get_app_config()` returning a fresh `AppConfig` does not retrigger it. |
-| `channels.*` IM platform credentials | `start_channel_service()` is invoked once during startup; live channels are not rebuilt on config change. |
+Infrastructure fields are **restart-required**. The authoritative list lives in `packages/harness/deerflow/config/reload_boundary.py::STARTUP_ONLY_FIELDS` and is mirrored by the standardised `"startup-only:"` prefix on the corresponding `Field(description=...)` in `AppConfig`, so IDE hover on those fields surfaces the reason inline (no need to context-switch into this table). Currently registered: `database`, `checkpointer`, `run_events`, `stream_bridge`, `sandbox`, `log_level`, `channels`. Adding a new restart-required field requires updating the registry; drift is pinned by `tests/test_reload_boundary.py`.

 Configuration priority:
 1. Explicit `config_path` argument
@@ -277,6 +273,7 @@ CORS is same-origin by default when requests enter through nginx on port 2026. S
 - When a persistent `RunStore` is configured, `get()` and `list_by_thread()` hydrate historical runs from the store. In-memory records win for the same `run_id` so task, abort, and stream-control state stays attached to active local runs.
 - `cancel()` and `create_or_reject(..., multitask_strategy="interrupt"|"rollback")` persist interrupted status through `RunStore.update_status()`, matching normal `set_status()` transitions.
 - Store-only hydrated runs are readable history. If the current worker has no in-memory task/control state for that run, cancellation APIs can return 409 because this worker cannot stop the task.
+- `POST /wait` (both thread-scoped and `/api/runs/wait`) drains the stream bridge via `wait_for_run_completion()` instead of bare `await record.task`, so it honours the run's `on_disconnect` setting and cancels the background run on real client disconnect rather than returning a stale checkpoint (issue #3265).

 Proxied through nginx: `/api/langgraph/*` → Gateway LangGraph-compatible runtime, all other `/api/*` → Gateway REST APIs.

@@ -342,7 +339,7 @@ Proxied through nginx: `/api/langgraph/*` → Gateway LangGraph-compatible runti
 - **Cache invalidation**: Detects config file changes via mtime comparison
 - **Transports**: stdio (command-based), SSE, HTTP
 - **OAuth (HTTP/SSE)**: Supports token endpoint flows (`client_credentials`, `refresh_token`) with automatic token refresh + Authorization header injection
- **Runtime updates**: Gateway API saves to extensions_config.json; LangGraph detects via mtime
+- **Runtime updates**: Gateway API saves to extensions_config.json; the Gateway-embedded runtime detects changes via mtime

 ### Skills System (`packages/harness/deerflow/skills/`)

@@ -369,7 +366,7 @@ Proxied through nginx: `/api/langgraph/*` → Gateway LangGraph-compatible runti

 ### IM Channels System (`app/channels/`)

-Bridges external messaging platforms (Feishu, Slack, Telegram, DingTalk) to the DeerFlow agent via the LangGraph Server.
+Bridges external messaging platforms (Feishu, Slack, Telegram, DingTalk) to the DeerFlow agent via Gateway's LangGraph-compatible API.


 **Architecture**: Channels communicate with Gateway through the `langgraph-sdk` HTTP client (same as the frontend), ensuring threads are created and managed server-side. The internal SDK client injects process-local internal auth plus a matching CSRF cookie/header pair so Gateway accepts state-changing thread/run requests from channel workers without relying on browser session cookies.
@@ -64,7 +64,7 @@ FROM builder AS dev
 # Install Docker CLI (for DooD: allows starting sandbox containers via host Docker socket)
 COPY --from=docker:cli /usr/local/bin/docker /usr/local/bin/docker

-EXPOSE 8001 2024
+EXPOSE 8001

 CMD ["sh", "-c", "cd backend && PYTHONPATH=. uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001"]

@@ -94,8 +94,8 @@ WORKDIR /app
 # Copy backend with pre-built virtualenv from builder
 COPY --from=builder /app/backend ./backend

-# Expose ports (gateway: 8001, langgraph: 2024)
-EXPOSE 8001 2024
+# Expose Gateway API port.
+EXPOSE 8001

 # Default command (can be overridden in docker-compose)
 CMD ["sh", "-c", "cd backend && PYTHONPATH=. uv run --no-sync uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001"]
@@ -7,16 +7,26 @@ import json
 import logging
 import re
 import threading
+import time
 from typing import Any, Literal

 from app.channels.base import Channel
 from app.channels.commands import KNOWN_CHANNEL_COMMANDS
-from app.channels.message_bus import InboundMessage, InboundMessageType, MessageBus, OutboundMessage, ResolvedAttachment
+from app.channels.message_bus import (
+    PENDING_CLARIFICATION_METADATA_KEY,
+    RESOLVED_FROM_PENDING_CLARIFICATION_METADATA_KEY,
+    InboundMessage,
+    InboundMessageType,
+    MessageBus,
+    OutboundMessage,
+    ResolvedAttachment,
+)
 from deerflow.config.paths import VIRTUAL_PATH_PREFIX, get_paths
 from deerflow.runtime.user_context import get_effective_user_id
 from deerflow.sandbox.sandbox_provider import get_sandbox_provider

 logger = logging.getLogger(__name__)
+PENDING_CLARIFICATION_TTL_SECONDS = 30 * 60


 def _is_feishu_command(text: str) -> bool:
@@ -56,6 +66,7 @@ class FeishuChannel(Channel):
        self._background_tasks: set[asyncio.Task] = set()
        self._running_card_ids: dict[str, str] = {}
        self._running_card_tasks: dict[str, asyncio.Task] = {}
+        self._pending_clarifications: dict[tuple[str, str], list[dict[str, Any]]] = {}
        self._CreateFileRequest = None
        self._CreateFileRequestBody = None
        self._CreateImageRequest = None
@@ -63,6 +74,16 @@ class FeishuChannel(Channel):
        self._GetMessageResourceRequest = None
        self._thread_lock = threading.Lock()

+    @staticmethod
+    def _non_empty_str(value: Any) -> str | None:
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+        return None
+
+    @staticmethod
+    def _pending_key(chat_id: str, user_id: str) -> tuple[str, str]:
+        return (chat_id, user_id)
+
    @property
    def supports_streaming(self) -> bool:
        return True
@@ -531,18 +552,25 @@ class FeishuChannel(Channel):
                        "[Feishu] failed to patch running card %s, falling back to final reply",
                        running_card_id,
                    )
-                    await self._reply_card(source_message_id, msg.text)
+                    fallback_card_id = await self._reply_card(source_message_id, msg.text)
+                    self._remember_thread_mapping(msg, source_message_id, fallback_card_id)
+                    self._remember_pending_clarification(msg, fallback_card_id)
                else:
+                    self._remember_thread_mapping(msg, source_message_id, running_card_id)
+                    self._remember_pending_clarification(msg, running_card_id)
                    logger.info("[Feishu] running card updated: source=%s card=%s", source_message_id, running_card_id)
            elif msg.is_final:
-                await self._reply_card(source_message_id, msg.text)
+                final_card_id = await self._reply_card(source_message_id, msg.text)
+                self._remember_thread_mapping(msg, source_message_id, final_card_id)
+                self._remember_pending_clarification(msg, final_card_id)
            elif awaited_running_card_task:
                logger.warning(
                    "[Feishu] running card task finished without message_id for source=%s, skipping duplicate non-final creation",
                    source_message_id,
                )
            else:
-                await self._ensure_running_card(source_message_id, msg.text)
+                created_card_id = await self._ensure_running_card(source_message_id, msg.text)
+                self._remember_thread_mapping(msg, source_message_id, created_card_id)

            if msg.is_final:
                self._running_card_ids.pop(source_message_id, None)
@@ -553,6 +581,129 @@ class FeishuChannel(Channel):

    # -- internal ----------------------------------------------------------

+    def _remember_thread_mapping(self, msg: OutboundMessage, *topic_ids: str | None) -> None:
+        store = self.config.get("channel_store")
+        if store is None or not msg.thread_id:
+            return
+
+        metadata_topic_ids = [
+            msg.metadata.get("message_id"),
+            msg.metadata.get("root_id"),
+            msg.metadata.get("parent_id"),
+            msg.metadata.get("thread_id"),
+            msg.metadata.get("topic_id"),
+        ]
+        user_id = ""
+        raw_user_id = msg.metadata.get("user_id")
+        if isinstance(raw_user_id, str):
+            user_id = raw_user_id
+
+        seen: set[str] = set()
+        for topic_id in [*topic_ids, *metadata_topic_ids]:
+            topic_id = self._non_empty_str(topic_id)
+            if not topic_id or topic_id in seen:
+                continue
+            seen.add(topic_id)
+            try:
+                store.set_thread_id(
+                    self.name,
+                    msg.chat_id,
+                    msg.thread_id,
+                    topic_id=topic_id,
+                    user_id=user_id,
+                )
+            except Exception:
+                logger.exception("[Feishu] failed to remember thread mapping for topic_id=%s", topic_id)
+
+    def _remember_pending_clarification(self, msg: OutboundMessage, card_message_id: str | None) -> None:
+        if not msg.is_final or msg.metadata.get(PENDING_CLARIFICATION_METADATA_KEY) is not True:
+            return
+
+        user_id = self._non_empty_str(msg.metadata.get("user_id"))
+        topic_id = self._non_empty_str(msg.metadata.get("topic_id"))
+        source_message_id = self._non_empty_str(msg.thread_ts) or self._non_empty_str(msg.metadata.get("message_id"))
+        if not (user_id and topic_id and msg.thread_id and source_message_id and card_message_id):
+            return
+
+        key = self._pending_key(msg.chat_id, user_id)
+        pending = {
+            "thread_id": msg.thread_id,
+            "topic_id": topic_id,
+            "source_message_id": source_message_id,
+            "card_message_id": card_message_id,
+            "created_at": time.time(),
+        }
+        with self._thread_lock:
+            # Plain-message clarification continuity is a short-lived in-memory
+            # hint; explicit Feishu replies are still covered by persisted
+            # message-id mappings.
+            self._pending_clarifications.setdefault(key, []).append(pending)
+        logger.info(
+            "[Feishu] pending clarification remembered: chat_id=%s user_id=%s topic_id=%s thread_id=%s",
+            msg.chat_id,
+            user_id,
+            topic_id,
+            msg.thread_id,
+        )
+
+    def _consume_pending_clarification(self, chat_id: str, user_id: str) -> dict[str, Any] | None:
+        key = self._pending_key(chat_id, user_id)
+        with self._thread_lock:
+            pending_items = self._pending_clarifications.get(key)
+            if not pending_items:
+                return None
+
+            now = time.time()
+            while pending_items:
+                pending = pending_items.pop(0)
+                created_at = pending.get("created_at")
+                if isinstance(created_at, (int, float)) and now - created_at <= PENDING_CLARIFICATION_TTL_SECONDS:
+                    if pending_items:
+                        self._pending_clarifications[key] = pending_items
+                    else:
+                        self._pending_clarifications.pop(key, None)
+                    return pending
+                logger.info("[Feishu] pending clarification expired: chat_id=%s user_id=%s", chat_id, user_id)
+
+            self._pending_clarifications.pop(key, None)
+            return None
+
+    def _ensure_pending_thread_mapping(self, chat_id: str, user_id: str, pending: dict[str, Any]) -> None:
+        store = self.config.get("channel_store")
+        topic_id = self._non_empty_str(pending.get("topic_id"))
+        thread_id = self._non_empty_str(pending.get("thread_id"))
+        if store is None or not topic_id or not thread_id:
+            return
+        try:
+            store.set_thread_id(self.name, chat_id, thread_id, topic_id=topic_id, user_id=user_id)
+        except Exception:
+            logger.exception("[Feishu] failed to restore pending clarification mapping for topic_id=%s", topic_id)
+
+    def _resolve_topic_id(
+        self,
+        chat_id: str,
+        msg_id: str,
+        *,
+        root_id: str | None,
+        parent_id: str | None,
+        thread_id: str | None,
+    ) -> tuple[str, bool]:
+        store = self.config.get("channel_store")
+        candidates = [root_id, parent_id, thread_id]
+
+        if store is not None:
+            for candidate in candidates:
+                candidate = self._non_empty_str(candidate)
+                if not candidate:
+                    continue
+                try:
+                    if store.get_thread_id(self.name, chat_id, topic_id=candidate):
+                        return candidate, True
+                except Exception:
+                    logger.exception("[Feishu] failed to resolve stored topic mapping for topic_id=%s", candidate)
+
+        return root_id or msg_id, False
+
    @staticmethod
    def _log_future_error(fut, name: str, msg_id: str) -> None:
        """Callback for run_coroutine_threadsafe futures to surface errors."""
@@ -593,7 +744,9 @@ class FeishuChannel(Channel):

            # root_id is set when the message is a reply within a Feishu thread.
            # Use it as topic_id so all replies share the same DeerFlow thread.
-            root_id = getattr(message, "root_id", None) or None
+            root_id = self._non_empty_str(getattr(message, "root_id", None))
+            parent_id = self._non_empty_str(getattr(message, "parent_id", None))
+            feishu_thread_id = self._non_empty_str(getattr(message, "thread_id", None))

            # Parse message content
            content = json.loads(message.content)
@@ -654,10 +807,12 @@ class FeishuChannel(Channel):
            text = text.strip()

            logger.info(
-                "[Feishu] parsed message: chat_id=%s, msg_id=%s, root_id=%s, sender=%s, text=%r",
+                "[Feishu] parsed message: chat_id=%s, msg_id=%s, root_id=%s, parent_id=%s, thread_id=%s, sender=%s, text=%r",
                chat_id,
                msg_id,
                root_id,
+                parent_id,
+                feishu_thread_id,
                sender_id,
                text[:100] if text else "",
            )
@@ -673,8 +828,24 @@ class FeishuChannel(Channel):
            else:
                msg_type = InboundMessageType.CHAT

-            # topic_id: use root_id for replies (same topic), msg_id for new messages (new topic)
-            topic_id = root_id or msg_id
+            # Prefer any platform message id that already maps to a DeerFlow
+            # thread. This keeps replies to bot clarification cards in the
+            # original conversation even when Feishu reports the card as root.
+            topic_id, resolved_from_stored_mapping = self._resolve_topic_id(
+                chat_id,
+                msg_id,
+                root_id=root_id,
+                parent_id=parent_id,
+                thread_id=feishu_thread_id,
+            )
+            resolved_from_pending = False
+            if msg_type == InboundMessageType.CHAT and not resolved_from_stored_mapping:
+                pending = self._consume_pending_clarification(chat_id, sender_id)
+                pending_topic_id = self._non_empty_str(pending.get("topic_id")) if pending else None
+                if pending_topic_id:
+                    topic_id = pending_topic_id
+                    self._ensure_pending_thread_mapping(chat_id, sender_id, pending)
+                    resolved_from_pending = True

            inbound = self._make_inbound(
                chat_id=chat_id,
@@ -683,7 +854,15 @@ class FeishuChannel(Channel):
                msg_type=msg_type,
                thread_ts=msg_id,
                files=files_list,
-                metadata={"message_id": msg_id, "root_id": root_id},
+                metadata={
+                    "message_id": msg_id,
+                    "root_id": root_id,
+                    "parent_id": parent_id,
+                    "thread_id": feishu_thread_id,
+                    "topic_id": topic_id,
+                    "user_id": sender_id,
+                    RESOLVED_FROM_PENDING_CLARIFICATION_METADATA_KEY: resolved_from_pending,
+                },
            )
            inbound.topic_id = topic_id

@@ -15,10 +15,18 @@ import httpx
 from langgraph_sdk.errors import ConflictError

 from app.channels.commands import KNOWN_CHANNEL_COMMANDS
-from app.channels.message_bus import InboundMessage, InboundMessageType, MessageBus, OutboundMessage, ResolvedAttachment
+from app.channels.message_bus import (
+    PENDING_CLARIFICATION_METADATA_KEY,
+    InboundMessage,
+    InboundMessageType,
+    MessageBus,
+    OutboundMessage,
+    ResolvedAttachment,
+)
 from app.channels.store import ChannelStore
 from app.gateway.csrf_middleware import CSRF_COOKIE_NAME, CSRF_HEADER_NAME, generate_csrf_token
 from app.gateway.internal_auth import create_internal_auth_headers
+from deerflow.config.paths import make_safe_user_id
 from deerflow.runtime.user_context import get_effective_user_id

 logger = logging.getLogger(__name__)
@@ -173,6 +181,8 @@ def _extract_response_text(result: dict | list) -> str:

        # Stop at the last human message — anything before it is a previous turn
        if msg_type == "human":
+            if _is_hidden_human_control_message(msg):
+                continue
            break

        # Check for tool messages from ask_clarification (interrupt case)
@@ -200,6 +210,54 @@ def _extract_response_text(result: dict | list) -> str:
    return ""


+def _messages_from_result(result: dict | list) -> list[Any]:
+    if isinstance(result, list):
+        return result
+    if isinstance(result, dict):
+        messages = result.get("messages", [])
+        if isinstance(messages, list):
+            return messages
+    return []
+
+
+def _current_turn_messages(result: dict | list) -> list[dict[str, Any]]:
+    messages = _messages_from_result(result)
+    current_turn: list[dict[str, Any]] = []
+    for msg in reversed(messages):
+        if not isinstance(msg, dict):
+            continue
+        if msg.get("type") == "human":
+            break
+        current_turn.append(msg)
+    current_turn.reverse()
+    return current_turn
+
+
+def _has_current_turn_clarification(result: dict | list) -> bool:
+    """Return True only when the current turn's final result is clarification."""
+    for msg in reversed(_current_turn_messages(result)):
+        msg_type = msg.get("type")
+        if msg_type == "tool":
+            return msg.get("name") == "ask_clarification"
+        if msg_type == "ai":
+            content = msg.get("content")
+            if isinstance(content, str):
+                if content:
+                    return False
+            elif content:
+                return False
+            if msg.get("tool_calls"):
+                return False
+    return False
+
+
+def _response_metadata(base_metadata: dict[str, Any], *, pending_clarification: bool = False) -> dict[str, Any]:
+    metadata = _slim_metadata(base_metadata)
+    if pending_clarification:
+        metadata[PENDING_CLARIFICATION_METADATA_KEY] = True
+    return metadata
+
+
 def _extract_text_content(content: Any) -> str:
    """Extract text from a streaming payload content field."""
    if isinstance(content, str):
@@ -313,6 +371,8 @@ def _extract_artifacts(result: dict | list) -> list[str]:
            continue
        # Stop at the last human message — anything before it is a previous turn
        if msg.get("type") == "human":
+            if _is_hidden_human_control_message(msg):
+                continue
            break
        # Look for AI messages with present_files tool calls
        if msg.get("type") == "ai":
@@ -325,6 +385,18 @@ def _extract_artifacts(result: dict | list) -> list[str]:
    return artifacts


+def _is_hidden_human_control_message(msg: Mapping[str, Any]) -> bool:
+    """Return whether a human message is an internal control message hidden from UI."""
+    if msg.get("type") != "human":
+        return False
+
+    additional_kwargs = msg.get("additional_kwargs")
+    if not isinstance(additional_kwargs, Mapping):
+        return False
+
+    return additional_kwargs.get("hide_from_ui") is True
+
+
 def _format_artifact_text(artifacts: list[str]) -> str:
    """Format artifact paths into a human-readable text block listing filenames."""
    import posixpath
@@ -599,12 +671,20 @@ class ChannelManager:
        configurable["checkpoint_ns"] = ""
        configurable["thread_id"] = thread_id

+        # ``user_id`` drives user-scoped filesystem buckets that only accept
+        # ``[A-Za-z0-9_-]``, so normalize the channel id and keep the raw value
+        # under ``channel_user_id`` for platform-facing lookups.
+        run_context_identity: dict[str, Any] = {"thread_id": thread_id}
+        if msg.user_id:
+            run_context_identity["user_id"] = make_safe_user_id(msg.user_id)
+            run_context_identity["channel_user_id"] = msg.user_id
+
        run_context = _merge_dicts(
            DEFAULT_RUN_CONTEXT,
            self._default_session.get("context"),
            channel_layer.get("context"),
            user_layer.get("context"),
-            {"thread_id": thread_id},
+            run_context_identity,
        )

        # Custom agents are implemented as lead_agent + agent_name context.
@@ -790,6 +870,7 @@ class ChannelManager:
                raise

        response_text = _extract_response_text(result)
+        pending_clarification = _has_current_turn_clarification(result)
        artifacts = _extract_artifacts(result)

        logger.info(
@@ -815,7 +896,7 @@ class ChannelManager:
            artifacts=artifacts,
            attachments=attachments,
            thread_ts=msg.thread_ts,
-            metadata=_slim_metadata(msg.metadata),
+            metadata=_response_metadata(msg.metadata, pending_clarification=pending_clarification),
        )
        logger.info("[Manager] publishing outbound message to bus: channel=%s, chat_id=%s", msg.channel_name, msg.chat_id)
        await self.bus.publish_outbound(outbound)
@@ -877,7 +958,7 @@ class ChannelManager:
                        text=latest_text,
                        is_final=False,
                        thread_ts=msg.thread_ts,
-                        metadata=_slim_metadata(msg.metadata),
+                        metadata=_response_metadata(msg.metadata),
                    )
                )
                last_published_text = latest_text
@@ -891,6 +972,7 @@ class ChannelManager:
        finally:
            result = last_values if last_values is not None else {"messages": [{"type": "ai", "content": latest_text}]}
            response_text = _extract_response_text(result)
+            pending_clarification = _has_current_turn_clarification(result)
            artifacts = _extract_artifacts(result)
            response_text, attachments = _prepare_artifact_delivery(thread_id, response_text, artifacts)

@@ -922,7 +1004,7 @@ class ChannelManager:
                    attachments=attachments,
                    is_final=True,
                    thread_ts=msg.thread_ts,
-                    metadata=_slim_metadata(msg.metadata),
+                    metadata=_response_metadata(msg.metadata, pending_clarification=pending_clarification),
                )
            )

@@ -13,6 +13,9 @@ from typing import Any

 logger = logging.getLogger(__name__)

+PENDING_CLARIFICATION_METADATA_KEY = "pending_clarification"
+RESOLVED_FROM_PENDING_CLARIFICATION_METADATA_KEY = "resolved_from_pending_clarification"
+

 # ---------------------------------------------------------------------------
 # Message types
@@ -17,6 +17,7 @@ Initialization is handled directly in ``app.py`` via :class:`AsyncExitStack`.

 from __future__ import annotations

+import asyncio
 import logging
 from collections.abc import AsyncGenerator, Callable
 from contextlib import AsyncExitStack, asynccontextmanager
@@ -33,6 +34,43 @@ from deerflow.runtime.runs.store.base import RunStore

 logger = logging.getLogger(__name__)

+# Upper bound (seconds) for draining in-flight runs during shutdown, before the
+# AsyncExitStack tears down the checkpointer (and its connection pool). Kept
+# local to avoid an app -> deps -> app import cycle. This is a *separate* budget
+# from ``app.gateway.app._SHUTDOWN_HOOK_TIMEOUT_SECONDS`` (currently also 5.0s,
+# which bounds channel-service stop): the two govern independent teardown steps
+# and may diverge, but both count toward the lifespan shutdown window — revisit
+# them together if their sum must stay within the server's graceful-shutdown
+# timeout.
+_RUN_DRAIN_TIMEOUT_SECONDS = 5.0
+
+
+async def _drain_inflight_runs(run_manager: RunManager) -> None:
+    """Drain in-flight runs before the checkpointer is torn down (issue #3373).
+
+    Shields the (internally-bounded) drain so that even if the lifespan
+    coroutine is itself cancelled mid-shutdown — a second SIGINT or the server's
+    graceful-shutdown timeout, i.e. the same signal storm behind #3373 — the
+    checkpointer pool is not closed while run tasks are still writing
+    checkpoints. On such a cancellation we let the already-running drain finish
+    (it is bounded by ``RunManager.shutdown``'s own timeout) and then propagate
+    the cancellation.
+    """
+    drain = asyncio.create_task(run_manager.shutdown(timeout=_RUN_DRAIN_TIMEOUT_SECONDS))
+    try:
+        await asyncio.shield(drain)
+    except asyncio.CancelledError:
+        # Re-shield so this second wait does not abandon the in-flight drain;
+        # it is bounded, so this cannot hang. Then re-raise to honour shutdown.
+        try:
+            await asyncio.shield(drain)
+        except Exception:
+            logger.exception("In-flight run drain failed after shutdown cancellation")
+        raise
+    except Exception:
+        logger.exception("Failed to drain in-flight runs during shutdown")
+
+
 if TYPE_CHECKING:
    from app.gateway.auth.local_provider import LocalAuthProvider
    from app.gateway.auth.repositories.sqlite import SQLiteUserRepository
@@ -81,6 +119,16 @@ def get_config() -> AppConfig:
    split-brain where the worker / lead-agent thread saw a stale startup
    snapshot.

+    Hot-reload boundary: fields backed by startup-time singletons
+    (engines, sandbox provider, IM channels, logging handler) require a
+    process restart to change at runtime. The authoritative list lives in
+    :mod:`deerflow.config.reload_boundary` and is mirrored by the
+    standardised ``"startup-only:"`` prefix on the matching
+    ``Field(description=...)`` in :class:`AppConfig` — IDE hover on those
+    fields will surface the boundary inline. See
+    ``backend/CLAUDE.md`` "Config Hot-Reload Boundary" for the operator
+    summary.
+
    Any failure to materialise the config (missing file, permission denied,
    YAML parse error, validation error) is reported as 503 — semantically
    "the gateway cannot serve requests without a usable configuration" — and
@@ -177,6 +225,14 @@ async def langgraph_runtime(app: FastAPI, startup_config: AppConfig) -> AsyncGen
        try:
            yield
        finally:
+            # Drain in-flight run tasks BEFORE the AsyncExitStack tears down the
+            # checkpointer (and its connection pool). A run still mid-graph would
+            # otherwise leak into asyncio.run() shutdown, where langgraph's
+            # _checkpointer_put_after_previous aput races the closed pool and
+            # raises PoolClosed (issue #3373).
+            run_manager = getattr(app.state, "run_manager", None)
+            if run_manager is not None:
+                await _drain_inflight_runs(run_manager)
            await close_engine()


@@ -10,6 +10,7 @@ from deerflow.runtime.user_context import DEFAULT_USER_ID

 INTERNAL_AUTH_HEADER_NAME = "X-DeerFlow-Internal-Token"
 INTERNAL_AUTH_ENV_VAR = "DEER_FLOW_INTERNAL_AUTH_TOKEN"
+INTERNAL_SYSTEM_ROLE = "internal"


 def _load_internal_auth_token() -> str:
@@ -34,4 +35,4 @@ def is_valid_internal_auth_token(token: str | None) -> bool:

 def get_internal_user():
    """Return the synthetic user used for trusted internal channel calls."""
-    return SimpleNamespace(id=DEFAULT_USER_ID, system_role="internal")
+    return SimpleNamespace(id=DEFAULT_USER_ID, system_role=INTERNAL_SYSTEM_ROLE)
@@ -0,0 +1,15 @@
+"""Shared pagination helpers for gateway routers."""
+
+from __future__ import annotations
+
+
+def trim_run_message_page(rows: list[dict], *, limit: int, after_seq: int | None) -> tuple[list[dict], bool]:
+    """Trim a ``limit + 1`` run-message page while preserving page boundaries."""
+    has_more = len(rows) > limit
+    if not has_more:
+        return rows, False
+
+    if after_seq is not None:
+        return rows[:limit], True
+
+    return rows[-limit:], True
@@ -276,10 +276,9 @@ async def update_mcp_configuration(request: McpConfigUpdateRequest) -> McpConfig

        logger.info(f"MCP configuration updated and saved to: {config_path}")

-        # NOTE: No need to reload/reset cache here - LangGraph Server (separate process)
-        # will detect config file changes via mtime and reinitialize MCP tools automatically
-
-        # Reload the configuration and update the global cache
+        # Reload the Gateway configuration and update the global cache. The
+        # agent runtime lives in Gateway, so this keeps API reads and tool
+        # execution aligned after extensions_config.json changes.
        reloaded_config = reload_extensions_config()
        servers = {name: _mask_server_config(McpServerConfigResponse(**server.model_dump())) for name, server in reloaded_config.mcp_servers.items()}
        return McpConfigResponse(mcp_servers=servers)
@@ -7,7 +7,6 @@ is reused so that conversation history is preserved across calls.

 from __future__ import annotations

-import asyncio
 import logging
 import uuid

@@ -16,8 +15,9 @@ from fastapi.responses import StreamingResponse

 from app.gateway.authz import require_permission
 from app.gateway.deps import get_checkpointer, get_feedback_repo, get_run_event_store, get_run_manager, get_run_store, get_stream_bridge
+from app.gateway.pagination import trim_run_message_page
 from app.gateway.routers.thread_runs import RunCreateRequest
-from app.gateway.services import sse_consumer, start_run
+from app.gateway.services import sse_consumer, start_run, wait_for_run_completion
 from deerflow.runtime import serialize_channel_values

 logger = logging.getLogger(__name__)
@@ -66,24 +66,25 @@ async def stateless_wait(body: RunCreateRequest, request: Request) -> dict:
    Otherwise a new temporary thread is created.
    """
    thread_id = _resolve_thread_id(body)
+    bridge = get_stream_bridge(request)
+    run_mgr = get_run_manager(request)
    record = await start_run(body, thread_id, request)

+    completed = True
    if record.task is not None:
-        try:
-            await record.task
-        except asyncio.CancelledError:
-            pass
+        completed = await wait_for_run_completion(bridge, record, request, run_mgr)

-    checkpointer = get_checkpointer(request)
-    config = {"configurable": {"thread_id": thread_id}}
-    try:
-        checkpoint_tuple = await checkpointer.aget_tuple(config)
-        if checkpoint_tuple is not None:
-            checkpoint = getattr(checkpoint_tuple, "checkpoint", {}) or {}
-            channel_values = checkpoint.get("channel_values", {})
-            return serialize_channel_values(channel_values)
-    except Exception:
-        logger.exception("Failed to fetch final state for run %s", record.run_id)
+    if completed:
+        checkpointer = get_checkpointer(request)
+        config = {"configurable": {"thread_id": thread_id}}
+        try:
+            checkpoint_tuple = await checkpointer.aget_tuple(config)
+            if checkpoint_tuple is not None:
+                checkpoint = getattr(checkpoint_tuple, "checkpoint", {}) or {}
+                channel_values = checkpoint.get("channel_values", {})
+                return serialize_channel_values(channel_values)
+        except Exception:
+            logger.exception("Failed to fetch final state for run %s", record.run_id)

    return {"status": record.status.value, "error": record.error}

@@ -129,8 +130,7 @@ async def run_messages(
        before_seq=before_seq,
        after_seq=after_seq,
    )
-    has_more = len(rows) > limit
-    data = rows[:limit] if has_more else rows
+    data, has_more = trim_run_message_page(rows, limit=limit, after_seq=after_seq)
    return {"data": data, "has_more": has_more}


@@ -21,7 +21,8 @@ from pydantic import BaseModel, Field

 from app.gateway.authz import require_permission
 from app.gateway.deps import get_checkpointer, get_current_user, get_feedback_repo, get_run_event_store, get_run_manager, get_run_store, get_stream_bridge
-from app.gateway.services import sse_consumer, start_run
+from app.gateway.pagination import trim_run_message_page
+from app.gateway.services import sse_consumer, start_run, wait_for_run_completion
 from deerflow.runtime import RunRecord, RunStatus, serialize_channel_values

 logger = logging.getLogger(__name__)
@@ -175,24 +176,25 @@ async def stream_run(thread_id: str, body: RunCreateRequest, request: Request) -
@require_permission("runs", "create", owner_check=True, require_existing=True)
 async def wait_run(thread_id: str, body: RunCreateRequest, request: Request) -> dict:
    """Create a run and block until it completes, returning the final state."""
+    bridge = get_stream_bridge(request)
+    run_mgr = get_run_manager(request)
    record = await start_run(body, thread_id, request)

+    completed = True
    if record.task is not None:
-        try:
-            await record.task
-        except asyncio.CancelledError:
-            pass
+        completed = await wait_for_run_completion(bridge, record, request, run_mgr)

-    checkpointer = get_checkpointer(request)
-    config = {"configurable": {"thread_id": thread_id}}
-    try:
-        checkpoint_tuple = await checkpointer.aget_tuple(config)
-        if checkpoint_tuple is not None:
-            checkpoint = getattr(checkpoint_tuple, "checkpoint", {}) or {}
-            channel_values = checkpoint.get("channel_values", {})
-            return serialize_channel_values(channel_values)
-    except Exception:
-        logger.exception("Failed to fetch final state for run %s", record.run_id)
+    if completed:
+        checkpointer = get_checkpointer(request)
+        config = {"configurable": {"thread_id": thread_id}}
+        try:
+            checkpoint_tuple = await checkpointer.aget_tuple(config)
+            if checkpoint_tuple is not None:
+                checkpoint = getattr(checkpoint_tuple, "checkpoint", {}) or {}
+                channel_values = checkpoint.get("channel_values", {})
+                return serialize_channel_values(channel_values)
+        except Exception:
+            logger.exception("Failed to fetch final state for run %s", record.run_id)

    return {"status": record.status.value, "error": record.error}

@@ -277,7 +279,12 @@ async def join_run(thread_id: str, run_id: str, request: Request) -> StreamingRe
    )


-@router.api_route("/{thread_id}/runs/{run_id}/stream", methods=["GET", "POST"], response_model=None)
+# Register GET and POST as separate routes so each method gets a unique OpenAPI
+# operationId. ``api_route(methods=["GET", "POST"])`` shares one route registration
+# across both methods, which makes FastAPI emit the same ``operationId`` twice and
+# warn about a duplicate operation id during OpenAPI generation.
+@router.get("/{thread_id}/runs/{run_id}/stream", response_model=None)
+@router.post("/{thread_id}/runs/{run_id}/stream", response_model=None)
@require_permission("runs", "read", owner_check=True)
 async def stream_existing_run(
    thread_id: str,
@@ -396,8 +403,7 @@ async def list_run_messages(
        before_seq=before_seq,
        after_seq=after_seq,
    )
-    has_more = len(rows) > limit
-    data = rows[:limit] if has_more else rows
+    data, has_more = trim_run_message_page(rows, limit=limit, after_seq=after_seq)
    return {"data": data, "has_more": has_more}


@@ -39,15 +39,39 @@ DEFAULT_MAX_FILE_SIZE = 50 * 1024 * 1024
 DEFAULT_MAX_TOTAL_SIZE = 100 * 1024 * 1024


+class UploadedFileInfo(BaseModel):
+    """Uploaded file metadata exposed by upload and list APIs."""
+
+    filename: str
+    size: int
+    path: str
+    virtual_path: str
+    artifact_url: str
+    extension: str | None = None
+    modified: float | None = None
+    original_filename: str | None = None
+    markdown_file: str | None = None
+    markdown_path: str | None = None
+    markdown_virtual_path: str | None = None
+    markdown_artifact_url: str | None = None
+
+
 class UploadResponse(BaseModel):
    """Response model for file upload."""

    success: bool
-    files: list[dict[str, str]]
+    files: list[UploadedFileInfo]
    message: str
    skipped_files: list[str] = Field(default_factory=list)


+class UploadListResponse(BaseModel):
+    """Response model for uploaded file listing."""
+
+    files: list[UploadedFileInfo]
+    count: int
+
+
 class UploadLimits(BaseModel):
    """Application-level upload limits exposed to clients."""

@@ -256,7 +280,7 @@ async def upload_files(

            file_info = {
                "filename": safe_filename,
-                "size": str(file_size),
+                "size": file_size,
                "path": str(sandbox_uploads / safe_filename),
                "virtual_path": virtual_path,
                "artifact_url": upload_artifact_url(thread_id, safe_filename),
@@ -333,9 +357,9 @@ async def get_upload_limits(
    return _get_upload_limits(config)


-@router.get("/list", response_model=dict)
+@router.get("/list", response_model=UploadListResponse)
@require_permission("threads", "read", owner_check=True)
-async def list_uploaded_files(thread_id: str, request: Request) -> dict:
+async def list_uploaded_files(thread_id: str, request: Request) -> UploadListResponse:
    """List all files in a thread's uploads directory."""
    try:
        uploads_dir = get_uploads_dir(thread_id)
@@ -349,7 +373,7 @@ async def list_uploaded_files(thread_id: str, request: Request) -> dict:
    for f in result["files"]:
        f["path"] = str(sandbox_uploads / f["filename"])

-    return result
+    return UploadListResponse(**result)


@router.delete("/{filename}")
@@ -19,6 +19,7 @@ from langchain_core.messages import BaseMessage
 from langchain_core.messages.utils import convert_to_messages

 from app.gateway.deps import get_run_context, get_run_manager, get_stream_bridge
+from app.gateway.internal_auth import INTERNAL_SYSTEM_ROLE
 from app.gateway.utils import sanitize_log_param
 from deerflow.config.app_config import get_app_config
 from deerflow.runtime import (
@@ -140,7 +141,14 @@ def merge_run_context_overrides(config: dict[str, Any], context: Mapping[str, An
    """Merge whitelisted keys from ``body.context`` into both ``config['configurable']``
    and ``config['context']`` so they are visible to legacy configurable readers and
    to LangGraph ``ToolRuntime.context`` consumers (e.g. the ``setup_agent`` tool —
-    see issue #2677)."""
+    see issue #2677).
+
+    ``user_id`` is intentionally propagated into ``config['context']`` in addition to
+    the whitelisted keys, so non-web callers (e.g. IM channels) that supply identity in
+    ``body.context`` keep it on ``ToolRuntime.context``. It is merged with
+    ``setdefault`` so a server-authenticated id stamped by
+    :func:`inject_authenticated_user_context` always wins over the client-supplied one.
+    """
    if not context:
        return
    configurable = config.setdefault("configurable", {})
@@ -151,6 +159,8 @@ def merge_run_context_overrides(config: dict[str, Any], context: Mapping[str, An
                configurable.setdefault(key, context[key])
            if isinstance(runtime_context, dict):
                runtime_context.setdefault(key, context[key])
+    if "user_id" in context and isinstance(runtime_context, dict):
+        runtime_context.setdefault("user_id", context["user_id"])


 def inject_authenticated_user_context(config: dict[str, Any], request: Request) -> None:
@@ -166,6 +176,9 @@ def inject_authenticated_user_context(config: dict[str, Any], request: Request)
    if user_id is None:
        return

+    if getattr(user, "system_role", None) == INTERNAL_SYSTEM_ROLE:
+        return
+
    runtime_context = config.setdefault("context", {})
    if isinstance(runtime_context, dict):
        runtime_context["user_id"] = str(user_id)
@@ -402,3 +415,51 @@ async def sse_consumer(
        if record.status in (RunStatus.pending, RunStatus.running):
            if record.on_disconnect == DisconnectMode.cancel:
                await run_mgr.cancel(record.run_id)
+
+
+async def wait_for_run_completion(
+    bridge: StreamBridge,
+    record: RunRecord,
+    request: Request,
+    run_mgr: RunManager,
+) -> bool:
+    """Block until the run publishes ``END_SENTINEL``, honouring on_disconnect.
+
+    The non-streaming ``/wait`` endpoints used to ``await record.task``
+    directly with no disconnect handling.  When the client (or an
+    intermediate HTTP proxy) timed out during a long tool call such as
+    ``pip install``, the handler would swallow ``CancelledError`` and
+    serialize whatever checkpoint happened to exist — masking a half-finished
+    run as a normal completion (issue #3265).
+
+    This helper consumes the same bridge that ``sse_consumer`` does so the
+    wait path shares its disconnect semantics: each wake-up polls
+    ``request.is_disconnected()``; on a real disconnect it cancels the
+    background run when ``record.on_disconnect`` is ``cancel``.  The bridge's
+    heartbeat sentinels guarantee at least one wake-up per
+    ``heartbeat_interval`` even when the agent emits no events for a while.
+
+    Returns:
+        ``True`` when ``END_SENTINEL`` was observed (run reached a terminal
+        state), ``False`` when the loop exited because the client
+        disconnected.  Callers must skip checkpoint serialization on
+        ``False`` so a partial checkpoint is not returned as a normal
+        response.
+    """
+    completed = False
+    try:
+        async for entry in bridge.subscribe(record.run_id):
+            # END_SENTINEL means the run reached a terminal state; honour it
+            # even if the client just disconnected so the caller still serializes
+            # the real final checkpoint.
+            if entry is END_SENTINEL:
+                completed = True
+                return True
+            if await request.is_disconnected():
+                break
+            # Heartbeats and regular events: keep waiting for END_SENTINEL.
+        return completed
+    finally:
+        if not completed and record.status in (RunStatus.pending, RunStatus.running):
+            if record.on_disconnect == DisconnectMode.cancel:
+                await run_mgr.cancel(record.run_id)
@@ -29,7 +29,7 @@ All other test plan sections were executed against either:
 | TC-DOCKER-03 | Per-worker rate limiter divergence | Confirms in-process `_login_attempts` dict doesn't share state across `gunicorn` workers (4 by default in the compose file); known limitation, documented | needs multi-worker container |
 | TC-DOCKER-04 | IM channels use internal Gateway auth | Verify Feishu/Slack/Telegram dispatchers attach the process-local internal auth header plus CSRF cookie/header when calling Gateway-compatible LangGraph APIs | needs `docker logs` |
 | TC-DOCKER-05 | Reset credentials surfacing | `reset_admin` writes a 0600 credential file in `DEER_FLOW_HOME` instead of logging plaintext. The file-based behavior is validated by non-Docker reset tests, so the only Docker-specific gap is verifying the volume mount carries the file out to the host | needs container + host volume |
-| TC-DOCKER-06 | Gateway-mode Docker deploy | `./scripts/deploy.sh --gateway` produces a 3-container topology (no `langgraph` container); same auth flow as standard mode | needs `docker compose --profile gateway` |
+| TC-DOCKER-06 | Docker deploy uses Gateway embedded runtime | `./scripts/deploy.sh` produces a Gateway + frontend + nginx topology (no `langgraph` container); same auth flow as local `make dev` | needs `docker compose up` |

 ## Coverage already provided by non-Docker tests

@@ -43,7 +43,7 @@ the test cases that ran on sg_dev or local:
 | TC-DOCKER-03 (per-worker rate limit) | TC-GW-04 + TC-REENT-09 (single-worker rate limit + 5min expiry). The cross-worker divergence is an architectural property of the in-memory dict; no auth code path differs |
 | TC-DOCKER-04 (IM channels use internal auth) | Code-level: `app/channels/manager.py` creates the `langgraph_sdk` client with `create_internal_auth_headers()` plus CSRF cookie/header, so channel workers do not rely on browser cookies |
 | TC-DOCKER-05 (credential surfacing) | `reset_admin` writes `.deer-flow/admin_initial_credentials.txt` with mode 0600 and logs only the path — the only Docker-unique step is whether the bind mount projects this path onto the host, which is a `docker compose` config check, not a runtime behavior change |
-| TC-DOCKER-06 (gateway-mode container) | Section 七 7.2 covered by TC-GW-01..05 + Section 二 (gateway-mode auth flow on sg_dev) — same Gateway code, container is just a packaging change |
+| TC-DOCKER-06 (Gateway embedded runtime container) | Section 七 7.2 covered by TC-GW-01..05 + Section 二 (Gateway auth flow on sg_dev) — same Gateway code, container is just a packaging change |

 ## Reproduction steps when Docker becomes available

@@ -4,10 +4,12 @@

 | 模式 | 启动命令 | Auth 层 | 端口 |
 |------|---------|---------|------|
-| 标准模式 | `make dev` | Gateway AuthMiddleware + LangGraph auth | 2026 (nginx) |
-| Gateway 模式 | `make dev-pro` | Gateway AuthMiddleware（全量） | 2026 (nginx) |
+| 标准模式 | `make dev` | Gateway AuthMiddleware（全量） | 2026 (nginx) |
 | 直连 Gateway | `cd backend && make gateway` | Gateway AuthMiddleware | 8001 |
-| 直连 LangGraph | `cd backend && make dev` | LangGraph auth | 2024 |
+| 直连 LangGraph 兼容性 | 手动运行 LangGraph 工具链时使用 | LangGraph auth | 2024 |
+
+`make dev`、Docker dev 和生产部署默认都运行 Gateway embedded runtime。
+`app.gateway.langgraph_auth` 仅用于保留的直连 LangGraph 工具链 / Studio 兼容性测试，不是标准服务启动路径。

 每种模式下都需执行以下测试。

@@ -21,10 +23,8 @@
 # 清除已有数据
 rm -f backend/.deer-flow/data/deerflow.db

-# 选择模式启动
-make dev          # 标准模式
-# 或
-make dev-pro      # Gateway 模式
+# 启动标准模式（Gateway embedded runtime）
+make dev
 ```

 **验证点：**
@@ -57,7 +57,7 @@ make dev

 ## 二、接口流程测试

-> 以下用 `BASE=http://localhost:2026` 为例。标准模式和 Gateway 模式都用此地址。
+> 以下用 `BASE=http://localhost:2026` 为例。标准模式经 nginx 暴露此地址。
 > 直连测试替换为对应端口。
 >
 > **CSRF token 提取**：多处用到从 cookie jar 提取 CSRF token，统一使用：
@@ -211,20 +211,18 @@ curl -s -X POST $BASE/api/threads/search \

 **预期：** 返回 0 或仅包含 user2 自己的 thread

-### 2.3 标准模式 LangGraph Server 隔离
+### 2.3 LangGraph-compatible Gateway 路由隔离

-> 仅在标准模式下测试。Gateway 模式不跑 LangGraph Server。
-
-#### TC-API-10: LangGraph 端点需要 cookie
+#### TC-API-10: LangGraph-compatible 端点需要 cookie

 ```bash
-# 不带 cookie 访问 LangGraph 接口
+# 不带 cookie 访问 LangGraph-compatible 接口
 curl -s -w "%{http_code}" $BASE/api/langgraph/threads
 ```

 **预期：** 401

-#### TC-API-11: LangGraph 带 cookie 可访问
+#### TC-API-11: LangGraph-compatible 路由带 cookie 可访问

 ```bash
 curl -s $BASE/api/langgraph/threads -b user1.txt | jq length
@@ -232,10 +230,10 @@ curl -s $BASE/api/langgraph/threads -b user1.txt | jq length

 **预期：** 200，返回 user1 的 thread 列表

-#### TC-API-12: LangGraph 隔离 — 用户只看到自己的
+#### TC-API-12: LangGraph-compatible 路由隔离 — 用户只看到自己的

 ```bash
-# user2 查 LangGraph threads
+# user2 查 threads
 curl -s $BASE/api/langgraph/threads -b user2.txt | jq length
 ```

@@ -1234,21 +1232,11 @@ P2=$(awk -F': ' '/^password:/ {print $2}' /tmp/deerflow-reset-p2.txt)
 ## 七、模式差异测试

 > 以下用 `GW=http://localhost:8001` 表示直连 Gateway，`BASE=http://localhost:2026` 表示经 nginx。
-> Gateway 模式启动命令：`make dev-pro`（或 `./scripts/serve.sh --dev --gateway`）。
+> 标准启动命令：`make dev`（或 `./scripts/serve.sh --dev`）。

-### 7.1 标准模式独有
+### 7.1 标准启动模式

-> 启动命令：`make dev`（或 `./scripts/serve.sh --dev`）
-
-#### TC-MODE-01: LangGraph Server 独立运行，需 cookie
-
-```bash
-# 无 cookie 访问 LangGraph
-curl -s -w "%{http_code}" -o /dev/null $BASE/api/langgraph/threads/search
-# 预期: 403（LangGraph auth handler 拒绝）
-```
-
-#### TC-MODE-02: LangGraph auth 的 token_version 检查
+#### TC-MODE-01: Gateway AuthMiddleware 的 token_version 检查

 ```bash
 # 登录拿 cookie
@@ -1261,9 +1249,9 @@ curl -s -X POST $BASE/api/v1/auth/change-password \
  -b cookies.txt -H "Content-Type: application/json" -H "X-CSRF-Token: $CSRF" \
  -d '{"current_password":"正确密码","new_password":"NewPass1!"}' -c new_cookies.txt

-# 用旧 cookie 访问 LangGraph
+# 用旧 cookie 访问 LangGraph-compatible 路由
 curl -s -w "%{http_code}" $BASE/api/langgraph/threads/search -b cookies.txt
-# 预期: 403（token_version 不匹配）
+# 预期: 401（token_version 不匹配）

 # 用新 cookie 访问
 CSRF2=$(grep csrf_token new_cookies.txt | awk '{print $NF}')
@@ -1272,7 +1260,7 @@ curl -s -w "%{http_code}" -X POST $BASE/api/langgraph/threads/search \
 # 预期: 200
 ```

-#### TC-MODE-03: LangGraph auth 的 owner filter 隔离
+#### TC-MODE-02: Gateway owner filter 隔离

 ```bash
 # user1 创建 thread
@@ -1297,18 +1285,9 @@ print('OK: user2 sees', len(threads), 'threads, none belong to user1')
 "
 ```

-### 7.2 Gateway 模式独有
-
-> 启动命令：`make dev-pro`（或 `./scripts/serve.sh --dev --gateway`）
-> 无 LangGraph Server 进程，agent runtime 嵌入 Gateway。
-
-#### TC-MODE-04: 所有请求经 AuthMiddleware
+#### TC-MODE-03: 所有请求经 AuthMiddleware

 ```bash
-# 确认 LangGraph Server 未运行
-curl -s -w "%{http_code}" -o /dev/null http://localhost:2024/ok
-# 预期: 000（连接被拒）
-
 # Gateway API 受保护
 curl -s -w "%{http_code}" -o /dev/null $BASE/api/models
 # 预期: 401
@@ -1319,7 +1298,7 @@ curl -s -w "%{http_code}" -o /dev/null -X POST $BASE/api/langgraph/threads/searc
 # 预期: 401
 ```

-#### TC-MODE-05: Gateway 模式下完整 auth 流程
+#### TC-MODE-04: 标准模式下完整 auth 流程

 ```bash
 # 登录
@@ -1334,7 +1313,7 @@ curl -s -X POST $BASE/api/langgraph/threads \
  -d '{"metadata":{}}' | python3 -c "import sys,json; print(json.load(sys.stdin)['thread_id'])"
 # 预期: 返回 thread_id

-# CSRF 保护（Gateway 模式下 CSRFMiddleware 直接覆盖所有路由）
+# CSRF 保护（CSRFMiddleware 覆盖所有 Gateway 路由）
 curl -s -w "%{http_code}" -o /dev/null -X POST $BASE/api/langgraph/threads \
  -b cookies.txt -H "Content-Type: application/json" -d '{"metadata":{}}'
 # 预期: 403（CSRF token missing）
@@ -1433,7 +1412,7 @@ done

 ### 7.4 Docker 部署

-> 启动命令：`./scripts/deploy.sh`（标准）或 `./scripts/deploy.sh --gateway`（Gateway 模式）
+> 启动命令：`./scripts/deploy.sh`
 > Docker Compose 文件：`docker/docker-compose.yaml`
 >
 > 前置条件：
@@ -1542,16 +1521,16 @@ docker logs deer-flow-gateway 2>&1 | grep -iE "Password: .{15,}" && echo "FAIL:
 - 容器日志输出**路径**（不是密码本身），符合 CodeQL `py/clear-text-logging-sensitive-data` 规则
 - `grep "Password:"` 在日志中**应当无匹配**（旧行为已废弃，simplify pass 移除了日志泄露路径）

-#### TC-DOCKER-06: Gateway 模式 Docker 部署
+#### TC-DOCKER-06: Docker 部署

 ```bash
-# Gateway 模式：无 langgraph 容器
-./scripts/deploy.sh --gateway
+# 标准 Docker 模式：runtime 嵌入 gateway 容器
+./scripts/deploy.sh
 sleep 15

-# 确认 langgraph 容器不存在
-docker ps --filter name=deer-flow-langgraph --format '{{.Names}}' | wc -l
-# 预期: 0
+# 确认 gateway 容器存在
+docker ps --filter name=deer-flow-gateway --format '{{.Names}}'
+# 预期: deer-flow-gateway

 # auth 流程正常：未登录受保护接口返回 401
 curl -s -w "%{http_code}" -o /dev/null $BASE/api/models
@@ -124,8 +124,8 @@ python -c "import secrets; print(secrets.token_urlsafe(32))"

 ## 兼容性

- **标准模式**（`make dev`）：完全兼容；无 admin 时访问 `/setup` 初始化
- **Gateway 模式**（`make dev-pro`）：完全兼容
+- **本地开发**（`make dev`）：Gateway embedded runtime 完全兼容；无 admin 时访问 `/setup` 初始化
+- **Gateway embedded runtime**：标准脚本、Docker dev 和生产部署均通过 Gateway 提供认证与 LangGraph-compatible API
 - **Docker 部署**：完全兼容，`.deer-flow/data/deerflow.db` 需持久化卷挂载
 - **IM 渠道**（Feishu/Slack/Telegram）：通过 Gateway 内部认证通信，使用 `default` 用户桶
 - **DeerFlowClient**（嵌入式）：不经过 HTTP，不受认证影响
@@ -0,0 +1,154 @@
+# Blocking IO detection usage and maintenance
+
+This document describes how to use and maintain DeerFlow backend blocking-IO
+detection for async event-loop safety.
+
+The goal is narrow: find and prevent synchronous IO from blocking backend
+async event-loop paths. Static and runtime detection are complementary, but
+they have different jobs.
+
+## Static detector
+
+The static detector is the discovery tool. It scans backend source code and
+reports candidate blocking-IO call sites that may need human review.
+
+Run it from the repository root:
+
+```bash
+make detect-blocking-io
+```
+
+Or from `backend/`:
+
+```bash
+make detect-blocking-io
+```
+
+The report is written to:
+
+```text
+.deer-flow/blocking-io-findings.json
+```
+
+Use this output for review and triage. A static finding is a candidate, not
+proof that production blocks the event loop at runtime. The current static
+rules are intentionally broad; prefer triaging existing output before adding
+new static rules.
+
+Add a static rule only when review finds a recurring high-risk blocking
+pattern that is invisible to the current detector.
+
+## Runtime detector
+
+The runtime detector is the CI regression guard. It uses Blockbuster to fail a
+focused test when code under `app.*` or `deerflow.*` performs blocking IO on
+the asyncio event-loop thread.
+
+Run it from `backend/`:
+
+```bash
+make test-blocking-io
+```
+
+The runtime gate starts from confirmed production bugs and protects those
+paths from regressing. It does not prove that the entire backend is free of
+blocking IO; it only covers the production paths exercised by
+`backend/tests/blocking_io/`.
+
+## Maintenance workflow
+
+Use the static detector to find candidates, then use review to decide which
+async production paths are worth protecting in CI.
+
+The normal workflow is:
+
+1. Run the static detector to find backend blocking-IO candidates.
+2. Use human review to pick high-risk production async paths.
+3. Add or update a focused runtime anchor in `backend/tests/blocking_io/`.
+4. Let CI prevent that path from regressing.
+
+Runtime detection has two maintenance paths.
+
+### Add a runtime rule
+
+Add a runtime rule when Blockbuster's default rules do not cover a generic
+blocking primitive used by production code.
+
+Rules belong in:
+
+```text
+backend/tests/support/detectors/blocking_io_runtime.py
+```
+
+Add them to `_PROJECT_BLOCKING_RULES`, not directly inside individual tests.
+Keeping rules centralized makes it clear which extra primitives DeerFlow
+expects Blockbuster to catch.
+
+Example shape:
+
+```python
+import subprocess
+
+from blockbuster import BlockBusterFunction
+
+_PROJECT_BLOCKING_RULES = (
+    (
+        "subprocess.Popen.__init__",
+        BlockBusterFunction(
+            subprocess.Popen,
+            "__init__",
+            scanned_modules=["app", "deerflow"],
+        ),
+    ),
+)
+```
+
+Do not add a runtime rule just because a business path is not tested. A rule
+only expands what Blockbuster can intercept after code runs.
+
+### Add a runtime anchor
+
+Add a runtime anchor when a high-risk async production path should be protected
+by CI but no existing `backend/tests/blocking_io/` test executes it.
+
+Anchors belong in:
+
+```text
+backend/tests/blocking_io/
+```
+
+A good anchor should:
+
+- Call the real production async entry point.
+- Avoid bypassing the blocking surface with test-only `asyncio.to_thread`
+  wrappers.
+- Use real local filesystem inputs when the bug shape is filesystem IO.
+- Mock only the external dependency boundary, such as a network service or
+  third-party saver class.
+- Fail if a future change moves the blocking operation back onto the event
+  loop.
+
+Avoid testing only the low-level helper unless that helper is the production
+async entry point. The runtime gate is most useful when it protects the caller
+that production actually executes.
+
+## Current runtime coverage
+
+The runtime anchors protect confirmed blocking-IO bug shapes:
+
+- SQLite checkpointer setup, including path resolution and parent-directory
+  creation.
+- Subagent skill metadata loading through `SubagentExecutor._load_skills()`.
+- `JsonlRunEventStore` async API (`put` / `list_*` / `delete_*`): the JSONL
+  run-event backend offloads its synchronous file IO via `asyncio.to_thread`
+  (fix #3084); this anchor drives the real async API under the gate so any
+  blocking IO reintroduced on the loop fails, not only removal of one
+  `to_thread` call.
+- `UploadsMiddleware.before_agent` uploads-directory scan: a sync-only middleware
+  hook runs on the event loop under async graph execution, so the scan is
+  offloaded via `abefore_agent` + `run_in_executor`.
+- Gate health checks: Blockbuster catches unoffloaded calls, opt-out works, and
+  patches are restored after exceptions.
+
+As static detection and review identify more high-risk async paths, add new
+runtime anchors incrementally.
@@ -36,6 +36,7 @@ models:
 - OpenAI (`langchain_openai:ChatOpenAI`)
 - Anthropic (`langchain_anthropic:ChatAnthropic`)
 - DeepSeek (`langchain_deepseek:ChatDeepSeek`)
+- Xiaomi MiMo (`deerflow.models.patched_mimo:PatchedChatMiMo`)
 - Claude Code OAuth (`deerflow.models.claude_provider:ClaudeChatModel`)
 - Codex CLI (`deerflow.models.openai_codex_provider:CodexChatModel`)
 - Any LangChain-compatible provider
@@ -94,20 +95,30 @@ models:
        thinking:
          type: enabled

-  - name: minimax-m2.5
-    display_name: MiniMax M2.5
+  - name: minimax-m3
+    display_name: MiniMax M3
    use: langchain_openai:ChatOpenAI
-    model: MiniMax-M2.5
+    model: MiniMax-M3
    api_key: $MINIMAX_API_KEY
    base_url: https://api.minimax.io/v1
    max_tokens: 4096
    temperature: 1.0  # MiniMax requires temperature in (0.0, 1.0]
    supports_vision: true

-  - name: minimax-m2.5-highspeed
-    display_name: MiniMax M2.5 Highspeed
+  - name: minimax-m2.7
+    display_name: MiniMax M2.7
    use: langchain_openai:ChatOpenAI
-    model: MiniMax-M2.5-highspeed
+    model: MiniMax-M2.7
+    api_key: $MINIMAX_API_KEY
+    base_url: https://api.minimax.io/v1
+    max_tokens: 4096
+    temperature: 1.0  # MiniMax requires temperature in (0.0, 1.0]
+    supports_vision: true
+
+  - name: minimax-m2.7-highspeed
+    display_name: MiniMax M2.7 Highspeed
+    use: langchain_openai:ChatOpenAI
+    model: MiniMax-M2.7-highspeed
    api_key: $MINIMAX_API_KEY
    base_url: https://api.minimax.io/v1
    max_tokens: 4096
@@ -166,6 +177,37 @@ models:

 For Gemini accessed **without** thinking (e.g. via OpenRouter where thinking is not activated), the plain `langchain_openai:ChatOpenAI` with `supports_thinking: false` is sufficient and no patch is needed.

+**MiMo with thinking via OpenAI-compatible API**:
+
+MiMo returns `reasoning_content` on assistant messages in thinking mode. In multi-turn agent conversations with tool calls, subsequent requests must preserve that historical `reasoning_content` on assistant messages or the MiMo API can return HTTP 400. Standard `langchain_openai:ChatOpenAI` drops this provider-specific field, so use `deerflow.models.patched_mimo:PatchedChatMiMo`:
+
+For pay-as-you-go API keys (`sk-...`), use `https://api.xiaomimimo.com/v1`. For Token Plan keys (`tp-...`), use the regional Token Plan Base URL shown in the MiMo console, such as `https://token-plan-cn.xiaomimimo.com/v1`. MiMo documents these key types as separate and non-interchangeable.
+
+`PatchedChatMiMo` is model-id agnostic. Use it for every MiMo thinking model entry you configure, including model entries referenced by `subagents.*.model` overrides (for example `mimo-v2.5-pro`, `mimo-v2.5`, `mimo-v2-pro`, `mimo-v2-omni`, or `mimo-v2-flash`).
+
+```yaml
+models:
+  - name: mimo-v2.5-pro
+    display_name: MiMo V2.5 Pro
+    use: deerflow.models.patched_mimo:PatchedChatMiMo
+    model: mimo-v2.5-pro
+    api_key: $MIMO_API_KEY
+    base_url: https://api.xiaomimimo.com/v1
+    max_tokens: 8192
+    supports_thinking: true
+    supports_vision: false
+    when_thinking_enabled:
+      extra_body:
+        thinking:
+          type: enabled
+    when_thinking_disabled:
+      extra_body:
+        thinking:
+          type: disabled
+```
+
+`PatchedChatMiMo` preserves MiMo's `choices[].message.reasoning_content`, streaming `delta.reasoning_content`, and request-history assistant `reasoning_content` fields. It does not reuse the DeepSeek provider.
+
 ### Tool Groups

 Organize tools into logical groups:
@@ -319,6 +361,7 @@ models:
 - `OPENAI_API_KEY` - OpenAI API key
 - `ANTHROPIC_API_KEY` - Anthropic API key
 - `DEEPSEEK_API_KEY` - DeepSeek API key
+- `MIMO_API_KEY` - Xiaomi MiMo API key
 - `NOVITA_API_KEY` - Novita API key (OpenAI-compatible endpoint)
 - `TAVILY_API_KEY` - Tavily search API key
 - `DEER_FLOW_PROJECT_ROOT` - Project root for relative runtime paths
@@ -19,6 +19,7 @@ This directory contains detailed documentation for the DeerFlow backend.
 | [STREAMING.md](STREAMING.md) | Token-level streaming design: Gateway vs DeerFlowClient paths, `stream_mode` semantics, per-id dedup |
 | [FILE_UPLOAD.md](FILE_UPLOAD.md) | File upload functionality |
 | [PATH_EXAMPLES.md](PATH_EXAMPLES.md) | Path types and usage examples |
+| [SANDBOX_MEMORY_PROFILING.md](SANDBOX_MEMORY_PROFILING.md) | Sandbox memory baseline and runtime comparison guide |
 | [summarization.md](summarization.md) | Context summarization feature |
 | [plan_mode_usage.md](plan_mode_usage.md) | Plan mode with TodoList |
 | [AUTO_TITLE_GENERATION.md](AUTO_TITLE_GENERATION.md) | Automatic title generation |
@@ -0,0 +1,81 @@
+# Sandbox Memory Profiling
+
+This guide records a repeatable baseline before changing the sandbox runtime.
+Issue #3213 reports per-sandbox memory near 1 GiB in Kubernetes. Before adding
+or recommending a new provider, capture the current AIO sandbox baseline and
+compare candidates with the same DeerFlow workload.
+
+## What to Measure
+
+Measure at least these samples:
+
+1. Empty sandbox after it becomes ready.
+2. After a simple bash command.
+3. After a Python task that imports common packages.
+4. After a Node task when Node-based workloads are expected.
+5. After generating files under `/mnt/user-data/outputs`.
+6. After release and warm reuse.
+7. At the target concurrency level, for example 10, 50, or 100 sandboxes.
+
+`kubectl top` reports Kubernetes/container working set memory. Treat it as a
+capacity signal, not exclusive RSS/PSS. Pod-level memory includes every
+container in the Pod and may include cache charged to the cgroup. If a result
+looks surprising, inspect the sandbox processes and cgroup metrics on the node
+before drawing conclusions.
+
+## Capture a Snapshot
+
+Run this from the repository root:
+
+```bash
+python scripts/sandbox_memory_profile.py \
+  --namespace deer-flow \
+  --selector app=deer-flow-sandbox \
+  --sample empty \
+  --include-processes \
+  --format markdown
+```
+
+Use a descriptive `--sample` value for each phase:
+
+```bash
+python scripts/sandbox_memory_profile.py --sample after-bash --format json
+python scripts/sandbox_memory_profile.py --sample after-python --format json
+python scripts/sandbox_memory_profile.py --sample after-artifact --format json
+```
+
+`--include-processes` runs `kubectl exec ... ps` in each sandbox Pod and adds
+the highest-RSS processes to the report. This helps distinguish Pod-level cgroup
+memory from process RSS. The two numbers will not match exactly because cgroup
+memory can include cache and other kernel-accounted memory.
+
+Save the raw JSON when comparing backends so totals, pod names, images,
+requests, limits, and timestamps can be audited later.
+
+## Candidate Runtime Matrix
+
+For AIO, CubeSandbox, OpenSandbox, gVisor, Kata, or another candidate, compare
+the same workload and record:
+
+| Area | Required Evidence |
+| --- | --- |
+| Capacity | Pod or instance count, total memory, average memory, max memory |
+| Startup | Ready latency at 1, 10, 50, and 100 concurrent sandboxes |
+| Commands | Bash output, timeout behavior, failure shape |
+| Files | `read_file`, `write_file`, binary `update_file`, `list_dir`, `glob`, `grep` |
+| Uploads | Files uploaded by the gateway are visible inside the sandbox |
+| Artifacts | Files written to `/mnt/user-data/outputs` are readable by the backend artifact API |
+| Paths | `/mnt/user-data/workspace`, `/mnt/user-data/uploads`, `/mnt/user-data/outputs`, `/mnt/acp-workspace`, and skills paths keep their expected semantics |
+| Isolation | Different users and threads cannot read each other's data |
+| Cleanup | Release, idle timeout, process restart, and orphan cleanup free resources |
+| Operations | Deployment prerequisites, privileged components, networking, storage, and upgrade path |
+
+## PR Guidance
+
+Do not claim that a new provider fixes high-concurrency memory usage until the
+same DeerFlow workload has been measured on both the current AIO sandbox and the
+candidate backend.
+
+For an experimental provider PR, prefer `Related to #3213` unless the PR also
+includes reproducible DeerFlow workload data that demonstrates the target memory
+reduction and preserves uploads, outputs, artifacts, and isolation behavior.
@@ -26,7 +26,7 @@
  - Replace sync `requests` with `httpx.AsyncClient` in community tools (tavily, jina_ai, firecrawl, infoquest, image_search)
  - [x] Replace sync `model.invoke()` with async `model.ainvoke()` in title_middleware and memory updater
  - Consider `asyncio.to_thread()` wrapper for remaining blocking file I/O
-  - For production: use `langgraph up` (multi-worker) instead of `langgraph dev` (single-worker)
+  - For production: tune Gateway worker/runtime settings for long-running agent workloads

 ## Resolved Issues

@@ -18,7 +18,10 @@ middleware, and the async path inside ``TitleMiddleware``. Any new in-graph
 ``create_chat_model`` call must add to this list and pass the flag.
 """

+from __future__ import annotations
+
 import logging
+from typing import TYPE_CHECKING

 from langchain.agents import create_agent
 from langchain.agents.middleware import AgentMiddleware
@@ -45,6 +48,11 @@ from deerflow.skills.tool_policy import filter_tools_by_skill_allowed_tools
 from deerflow.skills.types import Skill
 from deerflow.tracing import build_tracing_callbacks

+if TYPE_CHECKING:
+    from langchain.tools import BaseTool
+
+    from deerflow.tools.builtins.tool_search import DeferredToolSetup
+
 logger = logging.getLogger(__name__)


@@ -270,6 +278,7 @@ def _build_middlewares(
    custom_middlewares: list[AgentMiddleware] | None = None,
    *,
    app_config: AppConfig | None = None,
+    deferred_setup=None,
 ):
    """Build middleware chain based on runtime configuration.

@@ -318,11 +327,13 @@ def _build_middlewares(
    if model_config is not None and model_config.supports_vision:
        middlewares.append(ViewImageMiddleware())

-    # Add DeferredToolFilterMiddleware to hide deferred tool schemas from model binding
-    if resolved_app_config.tool_search.enabled:
+    # Hide deferred tool schemas from model binding until tool_search promotes them.
+    # The deferred set + catalog hash come from the build-time setup (assembled
+    # after tool-policy filtering); promotion is read from graph state.
+    if deferred_setup is not None and deferred_setup.deferred_names:
        from deerflow.agents.middlewares.deferred_tool_filter_middleware import DeferredToolFilterMiddleware

-        middlewares.append(DeferredToolFilterMiddleware())
+        middlewares.append(DeferredToolFilterMiddleware(deferred_setup.deferred_names, deferred_setup.catalog_hash))

    # Add SubagentLimitMiddleware to truncate excess parallel task calls
    subagent_enabled = cfg.get("subagent_enabled", False)
@@ -353,6 +364,26 @@ def _build_middlewares(
    return middlewares


+def _assemble_deferred(filtered_tools: list[BaseTool], *, enabled: bool) -> tuple[list[BaseTool], DeferredToolSetup]:
+    """Build the final tool list + deferred setup from a policy-filtered list.
+
+    Call AFTER tool-policy filtering so the deferred catalog never exposes a
+    tool the agent is not allowed to use. Fail-closed: if tool_search is enabled
+    and MCP tools survived filtering but no deferred set was recovered, raise
+    rather than silently binding their full schemas to the model.
+    """
+    from deerflow.tools.builtins.tool_search import build_deferred_tool_setup
+    from deerflow.tools.mcp_metadata import is_mcp_tool
+
+    deferred_setup = build_deferred_tool_setup(filtered_tools, enabled=enabled)
+    if enabled and not deferred_setup.deferred_names and any(is_mcp_tool(t) for t in filtered_tools):
+        raise RuntimeError("tool_search enabled and MCP tools survived policy filtering, but no deferred set was recovered — refusing to bind MCP schemas (fail-closed).")
+    final_tools = list(filtered_tools)
+    if deferred_setup.tool_search_tool:
+        final_tools.append(deferred_setup.tool_search_tool)
+    return final_tools, deferred_setup
+
+
 def _available_skill_names(agent_config, is_bootstrap: bool) -> set[str] | None:
    if is_bootstrap:
        return {"bootstrap"}
@@ -460,16 +491,19 @@ def _make_lead_agent(config: RunnableConfig, *, app_config: AppConfig):

    if is_bootstrap:
        # Special bootstrap agent with minimal prompt for initial custom agent creation flow
-        tools = get_available_tools(model_name=model_name, subagent_enabled=subagent_enabled, app_config=resolved_app_config) + [setup_agent]
+        raw_tools = get_available_tools(model_name=model_name, subagent_enabled=subagent_enabled, app_config=resolved_app_config) + [setup_agent]
+        filtered = filter_tools_by_skill_allowed_tools(raw_tools, skills_for_tool_policy)
+        final_tools, setup = _assemble_deferred(filtered, enabled=resolved_app_config.tool_search.enabled)
        return create_agent(
            model=create_chat_model(name=model_name, thinking_enabled=thinking_enabled, app_config=resolved_app_config, attach_tracing=False),
-            tools=filter_tools_by_skill_allowed_tools(tools, skills_for_tool_policy),
-            middleware=_build_middlewares(config, model_name=model_name, app_config=resolved_app_config),
+            tools=final_tools,
+            middleware=_build_middlewares(config, model_name=model_name, app_config=resolved_app_config, deferred_setup=setup),
            system_prompt=apply_prompt_template(
                subagent_enabled=subagent_enabled,
                max_concurrent_subagents=max_concurrent_subagents,
                available_skills=set(["bootstrap"]),
                app_config=resolved_app_config,
+                deferred_names=setup.deferred_names,
            ),
            state_schema=ThreadState,
        )
@@ -478,17 +512,20 @@ def _make_lead_agent(config: RunnableConfig, *, app_config: AppConfig):
    # The default agent (no agent_name) does not see this tool.
    extra_tools = [update_agent] if agent_name else []
    # Default lead agent (unchanged behavior)
-    tools = get_available_tools(model_name=model_name, groups=agent_config.tool_groups if agent_config else None, subagent_enabled=subagent_enabled, app_config=resolved_app_config)
+    raw_tools = get_available_tools(model_name=model_name, groups=agent_config.tool_groups if agent_config else None, subagent_enabled=subagent_enabled, app_config=resolved_app_config)
+    filtered = filter_tools_by_skill_allowed_tools(raw_tools + extra_tools, skills_for_tool_policy)
+    final_tools, setup = _assemble_deferred(filtered, enabled=resolved_app_config.tool_search.enabled)
    return create_agent(
        model=create_chat_model(name=model_name, thinking_enabled=thinking_enabled, reasoning_effort=reasoning_effort, app_config=resolved_app_config, attach_tracing=False),
-        tools=filter_tools_by_skill_allowed_tools(tools + extra_tools, skills_for_tool_policy),
-        middleware=_build_middlewares(config, model_name=model_name, agent_name=agent_name, app_config=resolved_app_config),
+        tools=final_tools,
+        middleware=_build_middlewares(config, model_name=model_name, agent_name=agent_name, app_config=resolved_app_config, deferred_setup=setup),
        system_prompt=apply_prompt_template(
            subagent_enabled=subagent_enabled,
            max_concurrent_subagents=max_concurrent_subagents,
            agent_name=agent_name,
            available_skills=set(agent_config.skills) if agent_config and agent_config.skills is not None else None,
            app_config=resolved_app_config,
+            deferred_names=setup.deferred_names,
        ),
        state_schema=ThreadState,
    )
@@ -542,6 +542,14 @@ combined with a FastAPI gateway for REST API access [citation:FastAPI](https://f
 {subagent_reminder}- Skill First: Always load the relevant skill before starting **complex** tasks.
 - Progressive Loading: Load resources incrementally as referenced in skills
 - Output Files: Final deliverables must be in `/mnt/user-data/outputs`
+- File Editing Workflow: When revising an existing file, prefer
+  `str_replace` over `write_file` — it sends only the diff and avoids
+  re-emitting the whole file (mirrors Claude Code's Edit and Codex's
+  apply_patch). When writing long new content from scratch, split it
+  into sections: the first `write_file` call creates the file, then use
+  `write_file` with append=True to extend it section by section. This
+  keeps each tool call small and avoids mid-stream chunk-gap timeouts
+  on oversized single-shot writes. (See issue #3189.)  
 - Clarity: Be direct and helpful, avoid unnecessary meta-commentary
 - Including Images and Mermaid: Images and Mermaid diagrams are always welcomed in the Markdown format, and you're encouraged to use `![Image Description](image_path)\n\n` or "```mermaid" to display images in response or Markdown files
 - Multi-task: Better utilize parallel tool calling to call multiple tools at one time for better performance
@@ -678,39 +686,23 @@ SOUL.md or config.yaml — those write into a temporary sandbox/tool workspace a
 Rules:
 - Always pass the FULL replacement text for `soul` (no patch semantics). Start from your current SOUL above and apply the user's edits.
 - Only pass the fields that should change. Omit the others to preserve them.
+- Never pass literal strings like `"null"`, `"none"`, or `"undefined"` for unchanged fields.
 - Pass `skills=[]` to disable all skills, or omit `skills` to keep the existing whitelist.
 - After `update_agent` returns successfully, tell the user the change is persisted and will take effect on the next turn.
 </self_update>
 """


-def get_deferred_tools_prompt_section(*, app_config: AppConfig | None = None) -> str:
-    """Generate <available-deferred-tools> block for the system prompt.
+def get_deferred_tools_prompt_section(*, deferred_names: frozenset[str] = frozenset()) -> str:
+    """Generate <available-deferred-tools> from an explicit deferred-name set.

-    Lists only deferred tool names so the agent knows what exists
-    and can use tool_search to load them.
-    Returns empty string when tool_search is disabled or no tools are deferred.
+    Lists only names so the agent knows what exists and can use tool_search to
+    load them. Returns empty string when there are no deferred tools. The set is
+    computed at agent build time (after tool-policy filtering) and passed in.
    """
-    from deerflow.tools.builtins.tool_search import get_deferred_registry
-
-    if app_config is None:
-        try:
-            from deerflow.config import get_app_config
-
-            config = get_app_config()
-        except Exception:
-            return ""
-    else:
-        config = app_config
-
-    if not config.tool_search.enabled:
+    if not deferred_names:
        return ""
-
-    registry = get_deferred_registry()
-    if not registry:
-        return ""
-
-    names = "\n".join(e.name for e in registry.entries)
+    names = "\n".join(sorted(deferred_names))
    return f"<available-deferred-tools>\n{names}\n</available-deferred-tools>"


@@ -772,6 +764,7 @@ def apply_prompt_template(
    agent_name: str | None = None,
    available_skills: set[str] | None = None,
    app_config: AppConfig | None = None,
+    deferred_names: frozenset[str] = frozenset(),
 ) -> str:
    # Include subagent section only if enabled (from runtime parameter)
    n = max_concurrent_subagents
@@ -799,7 +792,7 @@ def apply_prompt_template(
    skills_section = get_skills_prompt_section(available_skills, app_config=app_config)

    # Get deferred tools section (tool_search)
-    deferred_tools_section = get_deferred_tools_prompt_section(app_config=app_config)
+    deferred_tools_section = get_deferred_tools_prompt_section(deferred_names=deferred_names)

    # Build ACP agent section only if ACP agents are configured
    acp_section = _build_acp_section(app_config=app_config)
@@ -227,6 +227,110 @@ def _extract_text(content: Any) -> str:
    return str(content)


+_REQUIRED_MEMORY_UPDATE_TOP_LEVEL_KEYS = frozenset({"user", "history", "newFacts", "factsToRemove"})
+
+
+def _normalize_memory_update_fact(fact: Any) -> dict[str, Any] | None:
+    """Normalize a single fact entry from a model-produced memory update."""
+    if not isinstance(fact, dict):
+        return None
+
+    raw_content = fact.get("content")
+    if not isinstance(raw_content, str):
+        return None
+    content = raw_content.strip()
+    if not content:
+        return None
+
+    raw_category = fact.get("category")
+    category = raw_category.strip() if isinstance(raw_category, str) and raw_category.strip() else "context"
+
+    raw_confidence = fact.get("confidence", 0.5)
+    if isinstance(raw_confidence, bool):
+        return None
+    if isinstance(raw_confidence, str):
+        raw_confidence = raw_confidence.strip()
+        if not raw_confidence:
+            return None
+        try:
+            raw_confidence = float(raw_confidence)
+        except ValueError:
+            return None
+    elif isinstance(raw_confidence, (int, float)):
+        raw_confidence = float(raw_confidence)
+    else:
+        return None
+
+    if not math.isfinite(raw_confidence):
+        return None
+
+    normalized_fact = {
+        "content": content,
+        "category": category,
+        "confidence": raw_confidence,
+    }
+    source_error = fact.get("sourceError")
+    if isinstance(source_error, str):
+        normalized_source_error = source_error.strip()
+        if normalized_source_error:
+            normalized_fact["sourceError"] = normalized_source_error
+
+    return normalized_fact
+
+
+def _normalize_memory_update_data(update_data: dict[str, Any]) -> dict[str, Any]:
+    """Coerce parsed memory update data into the shape consumed by _apply_updates."""
+    user = update_data.get("user")
+    history = update_data.get("history")
+    new_facts = update_data.get("newFacts")
+    facts_to_remove = update_data.get("factsToRemove")
+    normalized_facts_to_remove = [fact_id for fact_id in facts_to_remove if isinstance(fact_id, str)] if isinstance(facts_to_remove, list) else []
+    normalized_new_facts = []
+    dropped_new_fact = not isinstance(new_facts, list)
+    if isinstance(new_facts, list):
+        for fact in new_facts:
+            normalized_fact = _normalize_memory_update_fact(fact)
+            if normalized_fact is not None:
+                normalized_new_facts.append(normalized_fact)
+            else:
+                dropped_new_fact = True
+
+    if normalized_facts_to_remove and dropped_new_fact:
+        raise json.JSONDecodeError(
+            "Unsafe partial memory update: factsToRemove with malformed newFacts",
+            json.dumps(update_data, ensure_ascii=False),
+            0,
+        )
+
+    return {
+        "user": user if isinstance(user, dict) else {},
+        "history": history if isinstance(history, dict) else {},
+        "newFacts": normalized_new_facts,
+        "factsToRemove": normalized_facts_to_remove,
+    }
+
+
+def _parse_memory_update_response(response_content: Any) -> dict[str, Any]:
+    """Parse the first valid memory-update JSON object from an LLM response.
+
+    Some providers may wrap JSON in thinking traces, prose, or markdown fences
+    even when prompted to return JSON only. This parser accepts safely
+    extractable JSON objects but does not repair truncated or malformed JSON.
+    """
+    response_text = _extract_text(response_content).strip()
+    decoder = json.JSONDecoder()
+
+    for match in re.finditer(r"\{", response_text):
+        try:
+            parsed, _end = decoder.raw_decode(response_text[match.start() :])
+        except json.JSONDecodeError:
+            continue
+        if isinstance(parsed, dict) and _REQUIRED_MEMORY_UPDATE_TOP_LEVEL_KEYS.issubset(parsed):
+            return _normalize_memory_update_data(parsed)
+
+    raise json.JSONDecodeError("No valid memory update JSON object found", response_text, 0)
+
+
 # Matches sentences that describe a file-upload *event* rather than general
 # file-related work.  Deliberately narrow to avoid removing legitimate facts
 # such as "User works with CSV files" or "prefers PDF export".
@@ -353,13 +457,7 @@ class MemoryUpdater:
        user_id: str | None = None,
    ) -> bool:
        """Parse the model response, apply updates, and persist memory."""
-        response_text = _extract_text(response_content).strip()
-
-        if response_text.startswith("```"):
-            lines = response_text.split("\n")
-            response_text = "\n".join(lines[1:-1] if lines[-1] == "```" else lines[1:])
-
-        update_data = json.loads(response_text)
+        update_data = _parse_memory_update_response(response_content)
        # Deep-copy before in-place mutation so a subsequent save() failure
        # cannot corrupt the still-cached original object reference.
        updated_memory = self._apply_updates(copy.deepcopy(current_memory), update_data, thread_id)
@@ -26,6 +26,11 @@ from langchain_core.messages import ToolMessage

 logger = logging.getLogger(__name__)

+# Workaround for issue #2894: malformed write_file calls can carry huge Markdown
+# payloads in invalid tool-call args. Keep recovery error details short so the
+# synthetic ToolMessage does not echo large or malformed content back to the model.
+_MAX_RECOVERY_ERROR_DETAIL_LEN = 500
+

 class DanglingToolCallMiddleware(AgentMiddleware[AgentState]):
    """Inserts placeholder ToolMessages for dangling tool calls before model invocation.
@@ -98,9 +103,25 @@ class DanglingToolCallMiddleware(AgentMiddleware[AgentState]):
    @staticmethod
    def _synthetic_tool_message_content(tool_call: dict) -> str:
        if tool_call.get("invalid"):
+            name = tool_call.get("name")
            error = tool_call.get("error")
-            if isinstance(error, str) and error:
-                return f"[Tool call could not be executed because its arguments were invalid: {error}]"
+            error_text = error[:_MAX_RECOVERY_ERROR_DETAIL_LEN] if isinstance(error, str) and error else ""
+            # Workaround for issue #2894: malformed write_file calls can carry huge Markdown
+            # payloads in invalid tool-call args. Keep recovery guidance actionable without
+            # echoing large or malformed content back to the model.
+            if name == "write_file":
+                details = f" Parser error: {error_text}" if error_text else ""
+                return (
+                    "[write_file failed before execution: the tool-call arguments were not valid JSON, "
+                    "so no file was written. This often happens when the model tries to write a very "
+                    "large Markdown file in a single tool call, especially when `content` contains "
+                    "unescaped quotes, inline JSON, backslashes, or code fences. Do not retry the same "
+                    "large `write_file` payload for this artifact; provide the report/content directly "
+                    "as normal assistant text in your next response. If a file write is still needed "
+                    f"later, split the file into smaller sections instead of one large payload.{details}]"
+                )
+            if error_text:
+                return f"[Tool call could not be executed because its arguments were invalid: {error_text}]"
            return "[Tool call could not be executed because its arguments were invalid.]"
        return "[Tool call was interrupted and did not return a result.]"

@@ -1,12 +1,15 @@
 """Middleware to filter deferred tool schemas from model binding.

-When tool_search is enabled, MCP tools are registered in the DeferredToolRegistry
-and passed to ToolNode for execution, but their schemas should NOT be sent to the
-LLM via bind_tools (that's the whole point of deferral — saving context tokens).
+When tool_search is enabled, MCP tools are still passed to ToolNode for
+execution, but their schemas must NOT be sent to the LLM via bind_tools until
+the model has discovered them via tool_search. This middleware removes the
+still-deferred tools from request.tools before model binding, and blocks tool
+calls to tools that have not been promoted yet.

-This middleware intercepts wrap_model_call and removes deferred tools from
-request.tools so that model.bind_tools only receives active tool schemas.
-The agent discovers deferred tools at runtime via the tool_search tool.
+The deferred name set and the catalog hash are injected at construction time
+(no ContextVar). Promotion state is read from graph state (``state["promoted"]``),
+scoped by catalog hash so a stale persisted promotion cannot expose a renamed
+or drifted tool.
 """

 import logging
@@ -24,47 +27,49 @@ logger = logging.getLogger(__name__)


 class DeferredToolFilterMiddleware(AgentMiddleware[AgentState]):
-    """Remove deferred tools from request.tools before model binding.
+    """Hide deferred tool schemas from the bound model until promoted.

    ToolNode still holds all tools (including deferred) for execution routing,
-    but the LLM only sees active tool schemas — deferred tools are discoverable
-    via tool_search at runtime.
+    but the LLM only sees active tool schemas plus tools that have already been
+    promoted (recorded in ``state["promoted"]`` under the current catalog hash).
    """

+    def __init__(self, deferred_names: frozenset[str], catalog_hash: str | None):
+        super().__init__()
+        self._deferred = deferred_names
+        self._catalog_hash = catalog_hash
+
+    def _promoted(self, state) -> set[str]:
+        promoted = (state or {}).get("promoted")
+        if promoted and promoted.get("catalog_hash") == self._catalog_hash:
+            return set(promoted.get("names") or [])
+        return set()
+
+    def _hidden(self, state) -> set[str]:
+        return set(self._deferred) - self._promoted(state)
+
    def _filter_tools(self, request: ModelRequest) -> ModelRequest:
-        from deerflow.tools.builtins.tool_search import get_deferred_registry
-
-        registry = get_deferred_registry()
-        if not registry:
+        if not self._deferred:
            return request
-
-        deferred_names = registry.deferred_names
-        active_tools = [t for t in request.tools if getattr(t, "name", None) not in deferred_names]
-
-        if len(active_tools) < len(request.tools):
-            logger.debug(f"Filtered {len(request.tools) - len(active_tools)} deferred tool schema(s) from model binding")
-
-        return request.override(tools=active_tools)
+        hide = self._hidden(request.state)
+        if not hide:
+            return request
+        active = [t for t in request.tools if getattr(t, "name", None) not in hide]
+        if len(active) < len(request.tools):
+            logger.debug("Filtered %d deferred tool schema(s) from model binding", len(request.tools) - len(active))
+        return request.override(tools=active)

    def _blocked_tool_message(self, request: ToolCallRequest) -> ToolMessage | None:
-        from deerflow.tools.builtins.tool_search import get_deferred_registry
-
-        registry = get_deferred_registry()
-        if not registry:
+        if not self._deferred:
            return None
-
-        tool_name = str(request.tool_call.get("name") or "")
-        if not tool_name:
+        name = str(request.tool_call.get("name") or "")
+        if not name or name not in self._hidden(request.state):
            return None
-
-        if not registry.contains(tool_name):
-            return None
-
        tool_call_id = str(request.tool_call.get("id") or "missing_tool_call_id")
        return ToolMessage(
-            content=(f"Error: Tool '{tool_name}' is deferred and has not been promoted yet. Call tool_search first to expose and promote this tool's schema, then retry."),
+            content=(f"Error: Tool '{name}' is deferred and has not been promoted yet. Call tool_search first to expose and promote this tool's schema, then retry."),
            tool_call_id=tool_call_id,
-            name=tool_name,
+            name=name,
            status="error",
        )

@@ -62,6 +62,41 @@ _AUTH_PATTERNS = (
    "未授权",
 )

+# Per-exception retry budget overrides.
+#
+# Some transient errors are retriable in principle but expensive to retry at
+# the default budget. StreamChunkTimeoutError in particular fires after the
+# upstream provider has already stalled for `stream_chunk_timeout` seconds
+# (typically 120-240s); a full 3-attempt loop can therefore stack 6-12 minutes
+# of dead air before surfacing the failure to the user. We keep exactly one
+# retry (cheap reconnect that catches genuine transient TCP blips) and then
+# fail fast — the same buffered payload is overwhelmingly likely to fail
+# again at the upstream provider for the same reason.
+#
+# Keys are exception class *names* (not classes) so we don't introduce
+# import-time coupling on optional dependencies like langchain-openai. The
+# value is the absolute max attempt count, NOT additional retries — so a
+# value of 2 means "1 first attempt + 1 retry" (the CR-requested
+# "keep one retry" behavior).
+_RETRY_BUDGET_OVERRIDES: dict[str, int] = {
+    "StreamChunkTimeoutError": 2,
+}
+
+# Exception class names that indicate the upstream stream-chunk watchdog
+# fired because the model stalled mid-flight. These deserve a more specific
+# user-facing message than the generic "temporarily unavailable" copy,
+# because the typical root cause is a long tool-call serialization stalling
+# the upstream stream — and the most actionable advice we can give the user
+# is "ask for a shorter / split output" rather than "wait and retry".
+# Generic connection drops (httpx RemoteProtocolError / ReadError) are
+# intentionally excluded: they routinely fire on transient network blips
+# with normal payloads, where the "split the work" guidance is misleading.
+_STREAM_DROP_EXCEPTIONS: frozenset[str] = frozenset(
+    {
+        "StreamChunkTimeoutError",
+    }
+)
+

 class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
    """Retry transient LLM errors and surface graceful assistant messages."""
@@ -83,6 +118,18 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
        self._circuit_state = "closed"
        self._circuit_probe_in_flight = False

+    def _max_attempts_for(self, exc: BaseException) -> int:
+        """Return the effective max attempt count for this exception.
+
+        Falls back to `self.retry_max_attempts` unless the exception class name
+        appears in the per-exception override table.
+        """
+        override = _RETRY_BUDGET_OVERRIDES.get(type(exc).__name__)
+        if override is None:
+            return self.retry_max_attempts
+
+        return min(override, self.retry_max_attempts)
+
    def _check_circuit(self) -> bool:
        """Returns True if circuit is OPEN (fast fail), False otherwise."""
        with self._circuit_lock:
@@ -153,6 +200,7 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
            "InternalServerError",
            "ReadError",  # httpx.ReadError: connection dropped mid-stream
            "RemoteProtocolError",  # httpx: server closed connection unexpectedly
+            "StreamChunkTimeoutError",  # langchain-openai: chunk gap exceeded stream_chunk_timeout
        }:
            return True, "transient"
        if status_code in _RETRIABLE_STATUS_CODES:
@@ -177,6 +225,24 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
    def _build_circuit_breaker_message(self) -> str:
        return "The configured LLM provider is currently unavailable due to continuous failures. Circuit breaker is engaged to protect the system. Please wait a moment before trying again."

+    def _build_error_fallback_message(
+        self,
+        content: str,
+        *,
+        error_type: str,
+        reason: str,
+        detail: str,
+    ) -> AIMessage:
+        return AIMessage(
+            content=content,
+            additional_kwargs={
+                "deerflow_error_fallback": True,
+                "error_type": error_type,
+                "error_reason": reason,
+                "error_detail": detail,
+            },
+        )
+
    def _build_user_message(self, exc: BaseException, reason: str) -> str:
        detail = _extract_error_detail(exc)
        if reason == "quota":
@@ -184,9 +250,31 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
        if reason == "auth":
            return "The configured LLM provider rejected the request because authentication or access is invalid. Please check the provider credentials and try again."
        if reason in {"busy", "transient"}:
+            # Stream-drop failures (chunk-gap timeout, peer-closed connection,
+            # raw read error) almost always point at a single oversized
+            # tool-call payload — the model spent so long serializing JSON
+            # arguments that the upstream provider buffered and the stream
+            # gap exceeded `stream_chunk_timeout`. Surfacing this distinct
+            # cause lets the user split or shorten their next request
+            # instead of helplessly retrying the same prompt.
+            if type(exc).__name__ in _STREAM_DROP_EXCEPTIONS:
+                return (
+                    "The model's streaming response was interrupted before it could "
+                    "finish. This usually happens when a single response or tool call "
+                    "is very large — please ask the assistant to split the work into "
+                    "smaller steps, or shorten the requested output, and try again."
+                )
            return "The configured LLM provider is temporarily unavailable after multiple retries. Please wait a moment and continue the conversation."
        return f"LLM request failed: {detail}"

+    def _build_user_fallback_message(self, exc: BaseException, reason: str) -> AIMessage:
+        return self._build_error_fallback_message(
+            self._build_user_message(exc, reason),
+            error_type=type(exc).__name__,
+            reason=reason,
+            detail=_extract_error_detail(exc),
+        )
+
    def _emit_retry_event(self, attempt: int, wait_ms: int, reason: str) -> None:
        try:
            from langgraph.config import get_stream_writer
@@ -212,7 +300,12 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
        handler: Callable[[ModelRequest], ModelResponse],
    ) -> ModelCallResult:
        if self._check_circuit():
-            return AIMessage(content=self._build_circuit_breaker_message())
+            return self._build_error_fallback_message(
+                self._build_circuit_breaker_message(),
+                error_type="CircuitBreakerOpen",
+                reason="circuit_open",
+                detail="LLM circuit breaker is open",
+            )

        attempt = 1
        while True:
@@ -228,7 +321,8 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
                raise
            except Exception as exc:
                retriable, reason = self._classify_error(exc)
-                if retriable and attempt < self.retry_max_attempts:
+                max_attempts = self._max_attempts_for(exc)
+                if retriable and attempt < max_attempts:
                    wait_ms = self._build_retry_delay_ms(attempt, exc)
                    logger.warning(
                        "Transient LLM error on attempt %d/%d; retrying in %dms: %s",
@@ -249,7 +343,7 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
                )
                if retriable:
                    self._record_failure()
-                return AIMessage(content=self._build_user_message(exc, reason))
+                return self._build_user_fallback_message(exc, reason)

    @override
    async def awrap_model_call(
@@ -258,7 +352,12 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
        handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
    ) -> ModelCallResult:
        if self._check_circuit():
-            return AIMessage(content=self._build_circuit_breaker_message())
+            return self._build_error_fallback_message(
+                self._build_circuit_breaker_message(),
+                error_type="CircuitBreakerOpen",
+                reason="circuit_open",
+                detail="LLM circuit breaker is open",
+            )

        attempt = 1
        while True:
@@ -274,7 +373,8 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
                raise
            except Exception as exc:
                retriable, reason = self._classify_error(exc)
-                if retriable and attempt < self.retry_max_attempts:
+                max_attempts = self._max_attempts_for(exc)
+                if retriable and attempt < max_attempts:
                    wait_ms = self._build_retry_delay_ms(attempt, exc)
                    logger.warning(
                        "Transient LLM error on attempt %d/%d; retrying in %dms: %s",
@@ -295,7 +395,7 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
                )
                if retriable:
                    self._record_failure()
-                return AIMessage(content=self._build_user_message(exc, reason))
+                return self._build_user_fallback_message(exc, reason)


 def _matches_any(detail: str, patterns: tuple[str, ...]) -> bool:
@@ -9,8 +9,9 @@ from typing import Any, Protocol, override, runtime_checkable

 from langchain.agents import AgentState
 from langchain.agents.middleware import SummarizationMiddleware
-from langchain_core.messages import AIMessage, AnyMessage, HumanMessage, RemoveMessage, ToolMessage
+from langchain_core.messages import AIMessage, AnyMessage, HumanMessage, RemoveMessage, ToolMessage, get_buffer_string
 from langgraph.config import get_config
+from langgraph.constants import TAG_NOSTREAM
 from langgraph.graph.message import REMOVE_ALL_MESSAGES
 from langgraph.runtime import Runtime

@@ -116,6 +117,74 @@ class DeerFlowSummarizationMiddleware(SummarizationMiddleware):
        self._preserve_recent_skill_count = max(0, preserve_recent_skill_count)
        self._preserve_recent_skill_tokens = max(0, preserve_recent_skill_tokens)
        self._preserve_recent_skill_tokens_per_skill = max(0, preserve_recent_skill_tokens_per_skill)
+        # The summary LLM call runs inside a LangGraph middleware hook, so its token
+        # stream would otherwise be captured by the messages-tuple stream callback and
+        # broadcast to the frontend as a phantom AI message. Tag a dedicated model copy
+        # with TAG_NOSTREAM so the streaming handler skips it.
+        # Keep self.model untagged so the parent's profile / ls_params inspection still works.
+        #
+        # Preserve any tags already bound on the model (e.g. "middleware:summarize" set in
+        # lead_agent/agent.py for RunJournal attribution): RunnableBinding.with_config does a
+        # shallow merge that would otherwise overwrite the existing tags list entirely.
+        existing_tags = list((getattr(self.model, "config", None) or {}).get("tags") or [])
+        merged_tags = [*existing_tags, TAG_NOSTREAM] if TAG_NOSTREAM not in existing_tags else existing_tags
+        self._summary_model = self.model.with_config(tags=merged_tags)
+
+    @override
+    def _create_summary(self, messages_to_summarize: list[AnyMessage]) -> str:
+        return self._summarize_with(messages_to_summarize)
+
+    @override
+    async def _acreate_summary(self, messages_to_summarize: list[AnyMessage]) -> str:
+        return await self._asummarize_with(messages_to_summarize)
+
+    def _summarize_with(self, messages_to_summarize: list[AnyMessage]) -> str:
+        """Mirror the parent ``_create_summary`` but invoke the nostream-tagged model.
+
+        We do not swap ``self.model`` at the instance level: the agent/middleware is
+        cached and reused across concurrent runs, so a temporary swap would leak the
+        ``RunnableBinding`` to other coroutines during ``await`` and break parent logic
+        that inspects the raw model (``profile`` / ``_get_ls_params``).
+        """
+        if not messages_to_summarize:
+            return "No previous conversation history."
+        prompt = self._build_summary_prompt(messages_to_summarize)
+        if prompt is None:
+            return "Previous conversation was too long to summarize."
+        try:
+            response = self._summary_model.invoke(
+                prompt,
+                config={"metadata": {"lc_source": "summarization"}},
+            )
+            return response.text.strip()
+        except Exception as e:
+            return f"Error generating summary: {e!s}"
+
+    async def _asummarize_with(self, messages_to_summarize: list[AnyMessage]) -> str:
+        """Async counterpart of :meth:`_summarize_with` using the nostream model."""
+        if not messages_to_summarize:
+            return "No previous conversation history."
+        prompt = self._build_summary_prompt(messages_to_summarize)
+        if prompt is None:
+            return "Previous conversation was too long to summarize."
+        try:
+            response = await self._summary_model.ainvoke(
+                prompt,
+                config={"metadata": {"lc_source": "summarization"}},
+            )
+            return response.text.strip()
+        except Exception as e:
+            return f"Error generating summary: {e!s}"
+
+    def _build_summary_prompt(self, messages_to_summarize: list[AnyMessage]) -> str | None:
+        """Build the summary prompt, returning ``None`` when trimming leaves nothing."""
+        trimmed_messages = self._trim_messages_for_summary(messages_to_summarize)
+        if not trimmed_messages:
+            return None
+        # Format messages to avoid token inflation from metadata when str() is called on
+        # message objects.
+        formatted_messages = get_buffer_string(trimmed_messages)
+        return self.summary_prompt.format(messages=formatted_messages).rstrip()

    def before_model(self, state: AgentState, runtime: Runtime) -> dict | None:
        return self._maybe_summarize(state, runtime)
@@ -77,9 +77,11 @@ def _build_runtime_middlewares(
    """Build shared base middlewares for agent execution."""
    from deerflow.agents.middlewares.llm_error_handling_middleware import LLMErrorHandlingMiddleware
    from deerflow.agents.middlewares.thread_data_middleware import ThreadDataMiddleware
+    from deerflow.agents.middlewares.tool_output_budget_middleware import ToolOutputBudgetMiddleware
    from deerflow.sandbox.middleware import SandboxMiddleware

    middlewares: list[AgentMiddleware] = [
+        ToolOutputBudgetMiddleware.from_app_config(app_config),
        ThreadDataMiddleware(lazy_init=lazy_init),
        SandboxMiddleware(lazy_init=lazy_init),
    ]
@@ -87,7 +89,7 @@ def _build_runtime_middlewares(
    if include_uploads:
        from deerflow.agents.middlewares.uploads_middleware import UploadsMiddleware

-        middlewares.insert(1, UploadsMiddleware())
+        middlewares.insert(2, UploadsMiddleware())

    if include_dangling_tool_call_patch:
        from deerflow.agents.middlewares.dangling_tool_call_middleware import DanglingToolCallMiddleware
@@ -0,0 +1,489 @@
+"""Middleware that enforces a per-result budget on tool outputs.
+
+Oversized tool results are persisted to disk and replaced with a compact
+preview containing a file reference.  When disk persistence is
+unavailable the middleware falls back to head+tail truncation so the
+model context is never blown by a single large tool return.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import uuid
+from collections.abc import Awaitable, Callable
+from dataclasses import replace as dc_replace
+from typing import Any, override
+
+from langchain.agents import AgentState
+from langchain.agents.middleware import AgentMiddleware
+from langchain.agents.middleware.types import ModelCallResult, ModelRequest, ModelResponse
+from langchain_core.messages import ToolMessage
+from langgraph.prebuilt.tool_node import ToolCallRequest
+from langgraph.types import Command
+
+from deerflow.config.tool_output_config import ToolOutputConfig
+
+logger = logging.getLogger(__name__)
+
+
+def _default_config() -> ToolOutputConfig:
+    return ToolOutputConfig()
+
+
+# ---------------------------------------------------------------------------
+# Text helpers
+# ---------------------------------------------------------------------------
+
+
+def _message_text(content: Any) -> str | None:
+    """Extract a plain-text representation from a ToolMessage content field.
+
+    Returns ``None`` for non-string / multimodal content so the caller
+    can skip budget enforcement (images, structured blocks, etc.).
+    """
+    if isinstance(content, str):
+        return content
+    if content is None:
+        return None
+    if isinstance(content, list):
+        pieces: list[str] = []
+        for part in content:
+            if isinstance(part, str):
+                pieces.append(part)
+            elif isinstance(part, dict) and isinstance(part.get("text"), str):
+                pieces.append(part["text"])
+            else:
+                return None
+        return "\n".join(pieces) if pieces else None
+    return None
+
+
+def _snap_to_line_boundary(text: str, pos: int) -> int:
+    """Return *pos* or the nearest preceding newline+1, whichever is closer.
+
+    Used so that previews and truncations end on a complete line when
+    possible.  If no newline exists in the second half of ``text[:pos]``
+    the original *pos* is returned unchanged.
+    """
+    if pos <= 0 or pos >= len(text):
+        return pos
+    half = pos // 2
+    nl = text.rfind("\n", half, pos)
+    if nl >= 0:
+        return nl + 1
+    return pos
+
+
+# ---------------------------------------------------------------------------
+# Disk persistence
+# ---------------------------------------------------------------------------
+
+_EXT_MAP: dict[str, str] = {
+    "bash": "log",
+    "bash_tool": "log",
+    "web_fetch": "log",
+}
+
+
+def _sanitize_tool_name(name: str) -> str:
+    """Strip path separators and traversal components from a tool name."""
+    base = os.path.basename(name)
+    safe = base.replace("..", "").replace("/", "_").replace("\\", "_")
+    return safe or "unknown"
+
+
+def _externalize(
+    content: str,
+    *,
+    tool_name: str,
+    tool_call_id: str,
+    outputs_path: str,
+    storage_subdir: str,
+) -> str | None:
+    """Write *content* to disk and return the virtual path, or ``None`` on failure."""
+    if os.path.isabs(storage_subdir) or ".." in storage_subdir:
+        return None
+    storage_dir = os.path.join(outputs_path, storage_subdir)
+    try:
+        os.makedirs(storage_dir, exist_ok=True)
+    except OSError:
+        return None
+
+    safe_name = _sanitize_tool_name(tool_name)
+    ext = _EXT_MAP.get(tool_name, "txt")
+    short_id = uuid.uuid4().hex[:12]
+    filename = f"{safe_name}-{short_id}.{ext}"
+    filepath = os.path.join(storage_dir, filename)
+
+    if not os.path.abspath(filepath).startswith(os.path.abspath(storage_dir)):
+        return None
+
+    try:
+        with open(filepath, "w", encoding="utf-8") as f:
+            f.write(content)
+    except OSError:
+        return None
+
+    virtual_base = "/mnt/user-data/outputs"
+    return f"{virtual_base}/{storage_subdir}/{filename}"
+
+
+# ---------------------------------------------------------------------------
+# Preview / fallback builders
+# ---------------------------------------------------------------------------
+
+
+def _build_preview(
+    content: str,
+    *,
+    tool_name: str,
+    virtual_path: str,
+    head_chars: int,
+    tail_chars: int,
+) -> str:
+    """Build a preview with a file reference for externalized output."""
+    total = len(content)
+    head_end = _snap_to_line_boundary(content, min(head_chars, total))
+    tail_start = max(head_end, total - tail_chars)
+    tail_start_snapped = _snap_to_line_boundary(content, tail_start)
+    if tail_start_snapped > head_end:
+        tail_start = tail_start_snapped
+
+    head = content[:head_end]
+    tail = content[tail_start:] if tail_start < total else ""
+
+    omitted = total - len(head) - len(tail)
+    ref = f"\n\n[Full {tool_name} output saved to {virtual_path} ({total} chars, ~{total // 4} tokens). Use read_file with start_line and end_line to access specific sections. {omitted} chars omitted from this preview.]\n\n"
+
+    parts = [head, ref]
+    if tail:
+        parts.append(tail)
+    return "".join(parts)
+
+
+def _build_fallback(
+    content: str,
+    *,
+    tool_name: str,
+    max_chars: int,
+    head_chars: int,
+    tail_chars: int,
+) -> str:
+    """Build a head+tail truncation when disk persistence is unavailable.
+
+    The returned string is guaranteed to be no longer than *max_chars*.
+    """
+    total = len(content)
+    if max_chars <= 0 or total <= max_chars:
+        return content
+
+    marker_template = "\n\n[... {n} chars omitted from {tn} output. Persistent storage unavailable. Consider narrowing the query or using more specific parameters.]\n\n"
+    marker_overhead = len(marker_template.format(n=total, tn=tool_name))
+
+    if marker_overhead >= max_chars:
+        return content[:max_chars]
+
+    budget = max_chars - marker_overhead
+    effective_head = min(head_chars, budget)
+    effective_tail = min(tail_chars, max(0, budget - effective_head))
+
+    head_end = _snap_to_line_boundary(content, min(effective_head, total))
+    tail_start = max(head_end, total - effective_tail)
+    tail_start_snapped = _snap_to_line_boundary(content, tail_start)
+    if tail_start_snapped > head_end:
+        tail_start = tail_start_snapped
+
+    head = content[:head_end]
+    tail = content[tail_start:] if tail_start < total else ""
+    omitted = total - len(head) - len(tail)
+
+    marker = marker_template.format(n=omitted, tn=tool_name)
+
+    parts = [head, marker]
+    if tail:
+        parts.append(tail)
+    return "".join(parts)
+
+
+# ---------------------------------------------------------------------------
+# Core budget logic
+# ---------------------------------------------------------------------------
+
+
+def _resolve_outputs_path(request: ToolCallRequest) -> str | None:
+    """Best-effort extraction of the thread outputs path."""
+    runtime = getattr(request, "runtime", None)
+    if runtime is None:
+        return None
+    state = getattr(runtime, "state", None)
+    if state is None:
+        return None
+    thread_data = state.get("thread_data")
+    if not isinstance(thread_data, dict):
+        return None
+    outputs_path = thread_data.get("outputs_path")
+    return outputs_path if isinstance(outputs_path, str) else None
+
+
+def _budget_content(
+    content: str,
+    *,
+    tool_name: str,
+    tool_call_id: str,
+    outputs_path: str | None,
+    config: ToolOutputConfig,
+) -> str | None:
+    """Apply budget to *content*. Returns ``None`` if no change needed."""
+    threshold = config.tool_overrides.get(tool_name, config.externalize_min_chars)
+    if threshold <= 0 and config.fallback_max_chars <= 0:
+        return None
+    if len(content) <= threshold and len(content) <= config.fallback_max_chars:
+        return None
+
+    if threshold > 0 and len(content) > threshold and outputs_path:
+        virtual_path = _externalize(
+            content,
+            tool_name=tool_name,
+            tool_call_id=tool_call_id,
+            outputs_path=outputs_path,
+            storage_subdir=config.storage_subdir,
+        )
+        if virtual_path is not None:
+            logger.info(
+                "Externalized %s output (%d chars) to %s",
+                tool_name,
+                len(content),
+                virtual_path,
+            )
+            return _build_preview(
+                content,
+                tool_name=tool_name,
+                virtual_path=virtual_path,
+                head_chars=config.preview_head_chars,
+                tail_chars=config.preview_tail_chars,
+            )
+
+    if config.fallback_max_chars > 0 and len(content) > config.fallback_max_chars:
+        logger.warning(
+            "Fallback-truncating %s output: %d chars → %d max",
+            tool_name,
+            len(content),
+            config.fallback_max_chars,
+        )
+        return _build_fallback(
+            content,
+            tool_name=tool_name,
+            max_chars=config.fallback_max_chars,
+            head_chars=config.fallback_head_chars,
+            tail_chars=config.fallback_tail_chars,
+        )
+
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Result patchers
+# ---------------------------------------------------------------------------
+
+
+def _patch_tool_message(msg: ToolMessage, config: ToolOutputConfig, outputs_path: str | None) -> ToolMessage:
+    """Apply budget to a single ToolMessage. Returns the original if unchanged."""
+    tool_name = msg.name or "unknown"
+    if tool_name in config.exempt_tools:
+        return msg
+
+    text = _message_text(msg.content)
+    if text is None:
+        return msg
+
+    replacement = _budget_content(
+        text,
+        tool_name=tool_name,
+        tool_call_id=msg.tool_call_id or "",
+        outputs_path=outputs_path,
+        config=config,
+    )
+    if replacement is None:
+        return msg
+
+    update: dict[str, Any] = {"content": replacement}
+    if getattr(msg, "response_metadata", None):
+        update["response_metadata"] = dict(msg.response_metadata)
+    if getattr(msg, "additional_kwargs", None):
+        update["additional_kwargs"] = dict(msg.additional_kwargs)
+    return msg.model_copy(update=update)
+
+
+def _effective_trigger(tool_name: str, config: ToolOutputConfig) -> int:
+    """Smallest content length that could trigger budgeting for *tool_name*.
+
+    Mirrors the trigger conditions in :func:`_budget_content` (per-tool
+    externalize threshold OR global fallback), so the pre-scan never produces
+    a false negative. Returns ``-1`` when nothing could ever trigger.
+    """
+    candidates: list[int] = []
+    externalize = config.tool_overrides.get(tool_name, config.externalize_min_chars)
+    if externalize > 0:
+        candidates.append(externalize)
+    if config.fallback_max_chars > 0:
+        candidates.append(config.fallback_max_chars)
+    return min(candidates) if candidates else -1
+
+
+def _tool_message_over_budget(msg: ToolMessage, config: ToolOutputConfig) -> bool:
+    """Cheap, per-tool-aware check: is this ToolMessage non-exempt and over its trigger?"""
+    if (msg.name or "") in config.exempt_tools:
+        return False
+    trigger = _effective_trigger(msg.name or "", config)
+    if trigger < 0:
+        return False
+    text = _message_text(msg.content)
+    return text is not None and len(text) > trigger
+
+
+def _needs_budget(result: ToolMessage | Command, config: ToolOutputConfig) -> bool:
+    """Fast check whether *result* could need budgeting (avoids thread offload for small outputs)."""
+    if isinstance(result, ToolMessage):
+        return _tool_message_over_budget(result, config)
+    update = getattr(result, "update", None)
+    if isinstance(update, dict):
+        for msg in update.get("messages", []):
+            if isinstance(msg, ToolMessage) and _tool_message_over_budget(msg, config):
+                return True
+    return False
+
+
+def _patch_result(result: ToolMessage | Command, config: ToolOutputConfig, outputs_path: str | None) -> ToolMessage | Command:
+    """Apply budget to a tool call result (ToolMessage or Command)."""
+    if isinstance(result, ToolMessage):
+        return _patch_tool_message(result, config, outputs_path)
+
+    update = getattr(result, "update", None)
+    if not isinstance(update, dict):
+        return result
+
+    messages = update.get("messages")
+    if not isinstance(messages, list):
+        return result
+
+    new_messages: list[Any] = []
+    changed = False
+    for msg in messages:
+        if isinstance(msg, ToolMessage):
+            patched = _patch_tool_message(msg, config, outputs_path)
+            if patched is not msg:
+                changed = True
+            new_messages.append(patched)
+        else:
+            new_messages.append(msg)
+
+    if not changed:
+        return result
+
+    return dc_replace(result, update={**update, "messages": new_messages})
+
+
+def _patch_model_messages(messages: list[Any], config: ToolOutputConfig) -> list[Any] | None:
+    """Apply budget to historical ToolMessages in a model request. Returns ``None`` if unchanged.
+
+    A cheap pre-scan bails out before allocating a new list when no historical
+    ToolMessage exceeds the budget — the common case once every result has
+    already been budgeted at tool-call time, so a long history is not rebuilt
+    on every model call.
+    """
+    if not any(isinstance(msg, ToolMessage) and _tool_message_over_budget(msg, config) for msg in messages):
+        return None
+
+    updated: list[Any] = []
+    changed = False
+    for msg in messages:
+        if isinstance(msg, ToolMessage):
+            patched = _patch_tool_message(msg, config, outputs_path=None)
+            if patched is not msg:
+                changed = True
+            updated.append(patched)
+        else:
+            updated.append(msg)
+    return updated if changed else None
+
+
+# ---------------------------------------------------------------------------
+# Middleware class
+# ---------------------------------------------------------------------------
+
+
+class ToolOutputBudgetMiddleware(AgentMiddleware[AgentState]):
+    """Enforce per-result budget on tool outputs via externalization or truncation."""
+
+    def __init__(self, config: ToolOutputConfig | None = None) -> None:
+        super().__init__()
+        self._config = config if config is not None else _default_config()
+
+    @classmethod
+    def from_app_config(cls, app_config: Any) -> ToolOutputBudgetMiddleware:
+        tool_output = getattr(app_config, "tool_output", None)
+        if isinstance(tool_output, ToolOutputConfig):
+            return cls(config=tool_output)
+        return cls()
+
+    # -- tool call hooks ---------------------------------------------------
+
+    @override
+    def wrap_tool_call(
+        self,
+        request: ToolCallRequest,
+        handler: Callable[[ToolCallRequest], ToolMessage | Command],
+    ) -> ToolMessage | Command:
+        result = handler(request)
+        if not self._config.enabled:
+            return result
+        if not _needs_budget(result, self._config):
+            return result
+        outputs_path = _resolve_outputs_path(request)
+        return _patch_result(result, self._config, outputs_path)
+
+    @override
+    async def awrap_tool_call(
+        self,
+        request: ToolCallRequest,
+        handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]],
+    ) -> ToolMessage | Command:
+        result = await handler(request)
+        if not self._config.enabled:
+            return result
+        if not _needs_budget(result, self._config):
+            return result
+        outputs_path = _resolve_outputs_path(request)
+        return await asyncio.to_thread(_patch_result, result, self._config, outputs_path)
+
+    # -- model call hooks (historical message truncation) ------------------
+
+    @override
+    def wrap_model_call(
+        self,
+        request: ModelRequest,
+        handler: Callable[[ModelRequest], ModelResponse],
+    ) -> ModelCallResult:
+        if self._config.enabled:
+            messages = getattr(request, "messages", None)
+            if isinstance(messages, list):
+                patched = _patch_model_messages(messages, self._config)
+                if patched is not None:
+                    request = request.override(messages=patched)
+        return handler(request)
+
+    @override
+    async def awrap_model_call(
+        self,
+        request: ModelRequest,
+        handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
+    ) -> ModelCallResult:
+        if self._config.enabled:
+            messages = getattr(request, "messages", None)
+            if isinstance(messages, list):
+                patched = _patch_model_messages(messages, self._config)
+                if patched is not None:
+                    request = request.override(messages=patched)
+        return await handler(request)
@@ -7,6 +7,7 @@ from typing import NotRequired, override
 from langchain.agents import AgentState
 from langchain.agents.middleware import AgentMiddleware
 from langchain_core.messages import HumanMessage
+from langchain_core.runnables import run_in_executor
 from langgraph.runtime import Runtime

 from deerflow.config.paths import Paths, get_paths
@@ -293,3 +294,16 @@ class UploadsMiddleware(AgentMiddleware[UploadsMiddlewareState]):
            "uploaded_files": new_files,
            "messages": messages,
        }
+
+    @override
+    async def abefore_agent(self, state: UploadsMiddlewareState, runtime: Runtime) -> dict | None:
+        """Async hook that offloads the synchronous uploads scan off the event loop.
+
+        ``before_agent`` performs blocking filesystem IO (directory enumeration,
+        ``stat``, reading sibling ``.md`` outlines). When the graph runs async,
+        langgraph would otherwise execute the sync hook directly on the event
+        loop, so it is dispatched to a worker thread via ``run_in_executor``.
+        ``run_in_executor`` copies the current context, so the ``user_id``
+        contextvar read by ``get_effective_user_id()`` is preserved.
+        """
+        return await run_in_executor(None, self.before_agent, state, runtime)
@@ -58,6 +58,32 @@ def merge_todos(existing: list | None, new: list | None) -> list | None:
    return new


+class PromotedTools(TypedDict):
+    catalog_hash: str
+    names: list[str]
+
+
+def merge_promoted(existing: PromotedTools | None, new: PromotedTools | None) -> PromotedTools | None:
+    """Reducer for deferred-tool promotions, scoped by catalog hash.
+
+    - new None/empty -> preserve existing (node didn't touch promotions).
+    - catalog_hash changed -> replace wholesale, dropping stale names (prevents a
+      persisted bare name from exposing a different tool after catalog drift).
+    - same catalog_hash -> union names, dedupe, preserve order.
+    """
+    if not new:
+        return existing
+    if existing is None or existing.get("catalog_hash") != new["catalog_hash"]:
+        return {
+            "catalog_hash": new["catalog_hash"],
+            "names": list(dict.fromkeys(new["names"])),
+        }
+    return {
+        "catalog_hash": existing["catalog_hash"],
+        "names": list(dict.fromkeys(existing["names"] + new["names"])),
+    }
+
+
 class ThreadState(AgentState):
    sandbox: NotRequired[SandboxState | None]
    thread_data: NotRequired[ThreadDataState | None]
@@ -66,3 +92,4 @@ class ThreadState(AgentState):
    todos: Annotated[list | None, merge_todos]
    uploaded_files: NotRequired[list[dict] | None]
    viewed_images: Annotated[dict[str, ViewedImageData], merge_viewed_images]  # image_path -> {base64, mime_type}
+    promoted: Annotated[PromotedTools | None, merge_promoted]
@@ -33,7 +33,7 @@ from langchain.agents.middleware import AgentMiddleware
 from langchain_core.messages import AIMessage, HumanMessage, SystemMessage, ToolMessage
 from langchain_core.runnables import RunnableConfig

-from deerflow.agents.lead_agent.agent import _build_middlewares
+from deerflow.agents.lead_agent.agent import _assemble_deferred, _build_middlewares
 from deerflow.agents.lead_agent.prompt import apply_prompt_template
 from deerflow.agents.thread_state import ThreadState
 from deerflow.config.agents_config import AGENT_NAME_PATTERN
@@ -237,19 +237,22 @@ class DeerFlowClient:
        subagent_enabled = cfg.get("subagent_enabled", False)
        max_concurrent_subagents = cfg.get("max_concurrent_subagents", 3)

+        tools = self._get_tools(model_name=model_name, subagent_enabled=subagent_enabled)
+        final_tools, deferred_setup = _assemble_deferred(tools, enabled=self._app_config.tool_search.enabled)
        kwargs: dict[str, Any] = {
            # attach_tracing=False because ``stream()`` injects tracing
            # callbacks at the graph invocation root so a single embedded run
            # produces one trace with correct session_id / user_id propagation.
            # Attaching them again on the model would emit duplicate spans.
            "model": create_chat_model(name=model_name, thinking_enabled=thinking_enabled, attach_tracing=False),
-            "tools": self._get_tools(model_name=model_name, subagent_enabled=subagent_enabled),
-            "middleware": _build_middlewares(config, model_name=model_name, agent_name=self._agent_name, custom_middlewares=self._middlewares),
+            "tools": final_tools,
+            "middleware": _build_middlewares(config, model_name=model_name, agent_name=self._agent_name, custom_middlewares=self._middlewares, deferred_setup=deferred_setup),
            "system_prompt": apply_prompt_template(
                subagent_enabled=subagent_enabled,
                max_concurrent_subagents=max_concurrent_subagents,
                agent_name=self._agent_name,
                available_skills=self._available_skills,
+                deferred_names=deferred_setup.deferred_names,
            ),
            "state_schema": ThreadState,
        }
@@ -1206,7 +1209,7 @@ class DeerFlowClient:

                info: dict[str, Any] = {
                    "filename": dest_name,
-                    "size": str(dest.stat().st_size),
+                    "size": dest.stat().st_size,
                    "path": str(dest),
                    "virtual_path": upload_virtual_path(dest_name),
                    "artifact_url": upload_artifact_url(thread_id, dest_name),
@@ -39,11 +39,63 @@ class AioSandbox(Sandbox):
        self._client = AioSandboxClient(base_url=base_url, timeout=600)
        self._home_dir = home_dir
        self._lock = threading.Lock()
+        self._closed = False

    @property
    def base_url(self) -> str:
        return self._base_url

+    def close(self) -> None:
+        """Best-effort close of the host-side HTTP client owned by this sandbox.
+
+        The agent_sandbox SDK is Fern-generated and exposes no ``close()`` /
+        ``__exit__``, so we reach the socket-owning ``httpx.Client`` explicitly
+        through its attribute chain::
+
+            Sandbox._client_wrapper        -> SyncClientWrapper
+                .httpx_client              -> Fern HttpClient (a wrapper, NOT httpx.Client)
+                    .httpx_client          -> httpx.Client     <- the real socket owner
+
+        Closing it releases pooled sockets so long-running provider lifecycles
+        do not accumulate unreclaimed host-side resources (#2872).
+
+        Resolution is most-specific-first with graceful degradation: if a future
+        SDK adds a top-level ``Sandbox.close()`` it is picked up automatically
+        without changing this code. Idempotent, thread-safe, and non-fatal:
+        failures during teardown are logged and swallowed so provider/backend
+        cleanup is never blocked.
+        """
+        with self._lock:
+            if self._closed:
+                return
+            self._closed = True
+            client = self._client
+            # Drop the reference under the lock for use-after-close safety: any
+            # later command on this instance fails loudly instead of reusing a
+            # half-closed client.
+            self._client = None
+
+        if client is None:
+            return
+
+        # Walk from the real httpx.Client up to the top-level client, picking the
+        # first object that actually exposes close().
+        wrapper = getattr(client, "_client_wrapper", None)
+        fern_http = getattr(wrapper, "httpx_client", None)
+        real_httpx = getattr(fern_http, "httpx_client", None)
+        target = next(
+            (c for c in (real_httpx, fern_http, client) if c is not None and hasattr(c, "close")),
+            None,
+        )
+        if target is None:
+            logger.debug("AioSandbox %s: no closable client found, nothing to release", self.id)
+            return
+
+        try:
+            target.close()
+        except Exception as e:
+            logger.warning(f"Error closing AioSandbox client for {self.id}: {e}")
+
    @property
    def home_dir(self) -> str:
        """Get the home directory inside the sandbox."""
@@ -790,14 +790,20 @@ class AioSandboxProvider(SandboxProvider):
        thread on its next turn without a cold-start.  The container will only be
        stopped when the replicas limit forces eviction or during shutdown.

+        The host-side HTTP client owned by the cached ``AioSandbox`` instance is
+        closed before the instance is dropped (#2872). The warm-pool entry only
+        stores ``SandboxInfo``, so a fresh ``AioSandbox`` (and a fresh client)
+        is constructed if the container is later reclaimed.
+
        Args:
            sandbox_id: The ID of the sandbox to release.
        """
        info = None
+        sandbox = None
        thread_ids_to_remove: list[str] = []

        with self._lock:
-            self._sandboxes.pop(sandbox_id, None)
+            sandbox = self._sandboxes.pop(sandbox_id, None)
            info = self._sandbox_infos.pop(sandbox_id, None)
            thread_ids_to_remove = [tid for tid, sid in self._thread_sandboxes.items() if sid == sandbox_id]
            for tid in thread_ids_to_remove:
@@ -807,6 +813,15 @@ class AioSandboxProvider(SandboxProvider):
            if info and sandbox_id not in self._warm_pool:
                self._warm_pool[sandbox_id] = (info, time.time())

+        if sandbox is not None:
+            # Defense-in-depth: close() already swallows its own errors; this
+            # guard only protects against a future close() that misbehaves, so
+            # host-side client cleanup can never block parking in the warm pool.
+            try:
+                sandbox.close()
+            except Exception as e:
+                logger.warning(f"Error closing sandbox {sandbox_id} during release: {e}")
+
        logger.info(f"Released sandbox {sandbox_id} to warm pool (container still running)")

    def destroy(self, sandbox_id: str) -> None:
@@ -815,14 +830,19 @@ class AioSandboxProvider(SandboxProvider):
        Unlike release(), this actually stops the container.  Use this for
        explicit cleanup, capacity-driven eviction, or shutdown.

+        The host-side HTTP client owned by the cached ``AioSandbox`` instance is
+        closed alongside backend/container destruction so no client/socket
+        resources leak (#2872).
+
        Args:
            sandbox_id: The ID of the sandbox to destroy.
        """
        info = None
+        sandbox = None
        thread_ids_to_remove: list[str] = []

        with self._lock:
-            self._sandboxes.pop(sandbox_id, None)
+            sandbox = self._sandboxes.pop(sandbox_id, None)
            info = self._sandbox_infos.pop(sandbox_id, None)
            thread_ids_to_remove = [tid for tid, sid in self._thread_sandboxes.items() if sid == sandbox_id]
            for tid in thread_ids_to_remove:
@@ -834,6 +854,15 @@ class AioSandboxProvider(SandboxProvider):
            else:
                self._warm_pool.pop(sandbox_id, None)

+        if sandbox is not None:
+            # Defense-in-depth: close() already swallows its own errors; this
+            # guard only protects against a future close() that misbehaves, so
+            # host-side client cleanup can never block container destruction.
+            try:
+                sandbox.close()
+            except Exception as e:
+                logger.warning(f"Error closing sandbox {sandbox_id} during destroy: {e}")
+
        if info:
            self._backend.destroy(info)
            logger.info(f"Destroyed sandbox {sandbox_id}")
@@ -18,6 +18,7 @@ from deerflow.config.guardrails_config import GuardrailsConfig, load_guardrails_
 from deerflow.config.loop_detection_config import LoopDetectionConfig
 from deerflow.config.memory_config import MemoryConfig, load_memory_config_from_dict
 from deerflow.config.model_config import ModelConfig
+from deerflow.config.reload_boundary import format_field_description
 from deerflow.config.run_events_config import RunEventsConfig
 from deerflow.config.runtime_paths import existing_project_file
 from deerflow.config.safety_finish_reason_config import SafetyFinishReasonConfig
@@ -30,6 +31,7 @@ from deerflow.config.summarization_config import SummarizationConfig, load_summa
 from deerflow.config.title_config import TitleConfig, load_title_config_from_dict
 from deerflow.config.token_usage_config import TokenUsageConfig
 from deerflow.config.tool_config import ToolConfig, ToolGroupConfig
+from deerflow.config.tool_output_config import ToolOutputConfig
 from deerflow.config.tool_search_config import ToolSearchConfig, load_tool_search_config_from_dict

 load_dotenv()
@@ -84,15 +86,27 @@ def apply_logging_level(name: str | None) -> None:
 class AppConfig(BaseModel):
    """Config for the DeerFlow application"""

-    log_level: str = Field(default="info", description="Logging level for deerflow and app modules (debug/info/warning/error); third-party libraries are not affected")
+    log_level: str = Field(
+        default="info",
+        description=format_field_description(
+            "log_level",
+            field_doc="Logging level for deerflow and app modules (debug/info/warning/error); third-party libraries are not affected.",
+        ),
+    )
    token_usage: TokenUsageConfig = Field(default_factory=TokenUsageConfig, description="Token usage tracking configuration")
    models: list[ModelConfig] = Field(default_factory=list, description="Available models")
-    sandbox: SandboxConfig = Field(description="Sandbox configuration")
+    sandbox: SandboxConfig = Field(
+        description=format_field_description(
+            "sandbox",
+            field_doc="Sandbox provider configuration (local filesystem or Docker-based aio sandbox).",
+        ),
+    )
    tools: list[ToolConfig] = Field(default_factory=list, description="Available tools")
    tool_groups: list[ToolGroupConfig] = Field(default_factory=list, description="Available tool groups")
    skills: SkillsConfig = Field(default_factory=SkillsConfig, description="Skills configuration")
    skill_evolution: SkillEvolutionConfig = Field(default_factory=SkillEvolutionConfig, description="Agent-managed skill evolution configuration")
    extensions: ExtensionsConfig = Field(default_factory=ExtensionsConfig, description="Extensions configuration (MCP servers and skills state)")
+    tool_output: ToolOutputConfig = Field(default_factory=ToolOutputConfig, description="Tool output budget protection configuration")
    tool_search: ToolSearchConfig = Field(default_factory=ToolSearchConfig, description="Tool search / deferred loading configuration")
    title: TitleConfig = Field(default_factory=TitleConfig, description="Automatic title generation configuration")
    summarization: SummarizationConfig = Field(default_factory=SummarizationConfig, description="Conversation summarization configuration")
@@ -105,10 +119,34 @@ class AppConfig(BaseModel):
    loop_detection: LoopDetectionConfig = Field(default_factory=LoopDetectionConfig, description="Loop detection middleware configuration")
    safety_finish_reason: SafetyFinishReasonConfig = Field(default_factory=SafetyFinishReasonConfig, description="Provider safety-filter finish_reason interception middleware configuration")
    model_config = ConfigDict(extra="allow")
-    database: DatabaseConfig = Field(default_factory=DatabaseConfig, description="Unified database backend configuration")
-    run_events: RunEventsConfig = Field(default_factory=RunEventsConfig, description="Run event storage configuration")
-    checkpointer: CheckpointerConfig | None = Field(default=None, description="Checkpointer configuration")
-    stream_bridge: StreamBridgeConfig | None = Field(default=None, description="Stream bridge configuration")
+    database: DatabaseConfig = Field(
+        default_factory=DatabaseConfig,
+        description=format_field_description(
+            "database",
+            field_doc="Unified database backend for run/feedback metadata (memory, sqlite, or postgres).",
+        ),
+    )
+    run_events: RunEventsConfig = Field(
+        default_factory=RunEventsConfig,
+        description=format_field_description(
+            "run_events",
+            field_doc="Run-event store backend (memory for dev, db for production queries, jsonl for lightweight single-node persistence).",
+        ),
+    )
+    checkpointer: CheckpointerConfig | None = Field(
+        default=None,
+        description=format_field_description(
+            "checkpointer",
+            field_doc="LangGraph state-persistence checkpointer configuration.",
+        ),
+    )
+    stream_bridge: StreamBridgeConfig | None = Field(
+        default=None,
+        description=format_field_description(
+            "stream_bridge",
+            field_doc="Stream bridge connecting agent workers to SSE endpoints.",
+        ),
+    )

    @classmethod
    def resolve_config_path(cls, config_path: str | None = None) -> Path:
@@ -5,7 +5,7 @@ import os
 from pathlib import Path
 from typing import Any, Literal

-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, model_validator

 from deerflow.config.runtime_paths import existing_project_file

@@ -47,6 +47,24 @@ class McpServerConfig(BaseModel):
    description: str = Field(default="", description="Human-readable description of what this MCP server provides")
    model_config = ConfigDict(extra="allow")

+    @model_validator(mode="before")
+    @classmethod
+    def _accept_transport_alias(cls, data: Any) -> Any:
+        """Accept the MCP-spec ``transport`` field as an alias for ``type``.
+
+        The official MCP configuration schema uses ``transport`` to indicate
+        the transport mechanism (``stdio``/``sse``/``http``). Earlier versions
+        of this project only honored ``type``, which caused remote SSE/HTTP
+        servers configured with just ``transport`` to be incorrectly treated as
+        ``stdio`` (the default). This validator normalizes the two so either
+        spelling works, with ``type`` taking precedence when both are provided.
+        """
+        if isinstance(data, dict):
+            transport = data.get("transport")
+            if transport and not data.get("type"):
+                data = {**data, "type": transport}
+        return data
+

 class SkillStateConfig(BaseModel):
    """Configuration for a single skill's state."""
@@ -32,6 +32,16 @@ class ModelConfig(BaseModel):
        description="Extra settings to be passed to the model when thinking is disabled",
    )
    supports_vision: bool = Field(default_factory=lambda: False, description="Whether the model supports vision/image inputs")
+    stream_chunk_timeout: float | None = Field(
+        default=None,
+        description=(
+            "Maximum seconds to wait between successive streaming chunks before "
+            "langchain-openai raises StreamChunkTimeoutError. None means use the "
+            "factory default (240s for OpenAI-compatible clients). Tune higher for "
+            "reasoning models with long thinking pauses; lower for latency-sensitive "
+            "interactive endpoints. Has no effect on non-OpenAI-compatible providers."
+        ),
+    )
    thinking: dict | None = Field(
        default_factory=lambda: None,
        description=(
@@ -1,3 +1,4 @@
+import hashlib
 import os
 import re
 import shutil
@@ -10,6 +11,8 @@ VIRTUAL_PATH_PREFIX = "/mnt/user-data"

 _SAFE_THREAD_ID_RE = re.compile(r"^[A-Za-z0-9_\-]+$")
 _SAFE_USER_ID_RE = re.compile(r"^[A-Za-z0-9_\-]+$")
+_UNSAFE_USER_ID_CHAR_RE = re.compile(r"[^A-Za-z0-9_\-]")
+_SAFE_USER_ID_DIGEST_HEX_LEN = 16


 def _default_local_base_dir() -> Path:
@@ -31,6 +34,23 @@ def _validate_user_id(user_id: str) -> str:
    return user_id


+def make_safe_user_id(raw: str) -> str:
+    """Normalize an external identity into the user-id charset (``[A-Za-z0-9_-]``).
+
+    IM channel ids (Feishu/Slack/Telegram) may contain characters that
+    :func:`_validate_user_id` rejects. Already-safe ids pass through unchanged;
+    lossy ones get a short digest suffix so two distinct inputs never share a
+    storage bucket.
+    """
+    if not raw:
+        raise ValueError("user_id must be a non-empty string.")
+    sanitized = _UNSAFE_USER_ID_CHAR_RE.sub("-", raw)
+    if sanitized == raw:
+        return raw
+    digest = hashlib.sha1(raw.encode("utf-8")).hexdigest()[:_SAFE_USER_ID_DIGEST_HEX_LEN]
+    return f"{sanitized}-{digest}"
+
+
 def _join_host_path(base: str, *parts: str) -> str:
    """Join host filesystem path segments while preserving native style.

@@ -0,0 +1,104 @@
+"""Single source of truth for the config hot-reload boundary.
+
+Bytedance/deer-flow issue #3144: gateway request dependencies resolve
+``AppConfig`` through ``get_app_config()`` on every request, so per-run
+fields take effect on the next message without restarting the gateway.
+The fields listed in this module are the **infrastructure** subset that
+the gateway captures once at startup — engines, singletons, IM clients,
+the logging handler — and that therefore require a process restart to
+change at runtime.
+
+The registry covers two kinds of entries:
+
+- Top-level ``AppConfig`` fields (``database``, ``checkpointer``,
+  ``run_events``, ``stream_bridge``, ``sandbox``, ``log_level``). For
+  these, :func:`format_field_description` produces the standardised
+  ``"startup-only: ..."`` prefix that the matching Pydantic
+  ``Field(description=...)`` carries, so the boundary surfaces in IDE
+  hover next to the field itself.
+- Top-level ``config.yaml`` sections that are not part of the
+  ``AppConfig`` schema (``channels``). These cannot be standardised at
+  the schema level, so the registry is their only canonical location.
+
+Any future "needs restart" scanner — operator tooling, lint hooks, doc
+generators — should drive off this registry rather than re-parsing
+prose.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+#: The standardised prefix every restart-required field description starts
+#: with. ``test_reload_boundary`` enforces both directions: registered
+#: fields must use this prefix in the schema, and any schema field using
+#: this prefix must be in the registry.
+STARTUP_ONLY_PREFIX = "startup-only:"
+
+
+#: Restart-required field paths mapped to the human-readable reason.
+#:
+#: The reason text is what surfaces in ``Field(description=...)``, so it
+#: must explain *what* code captures the snapshot — not just that the
+#: field is restart-required — so an operator changing the value knows
+#: which subsystem to restart.
+STARTUP_ONLY_FIELDS: dict[str, str] = {
+    "database": ("init_engine_from_config() runs once during langgraph_runtime() startup; the SQLAlchemy engine holds the connection pool and is not rebuilt on config.yaml edits."),
+    "checkpointer": ("make_checkpointer() binds the persistent checkpointer once at startup, including SQLite WAL / busy_timeout settings."),
+    "run_events": ("make_run_event_store() picks the memory- vs SQL-backed implementation at startup and is frozen onto app.state.run_events_config to stay paired with the underlying event store."),
+    "stream_bridge": ("make_stream_bridge() constructs the stream-bridge singleton once during startup."),
+    "sandbox": ("get_sandbox_provider() caches the provider singleton (``_default_sandbox_provider``); a different ``sandbox.use`` class path only takes effect on next process start."),
+    "log_level": (
+        "apply_logging_level() runs only during app.py startup; it sets the deerflow/app logger levels and may lower root handler thresholds so configured messages can propagate. A freshly reloaded AppConfig does not retrigger it."
+    ),
+    # Not part of the AppConfig Pydantic schema — channel credentials are
+    # consumed directly by ``start_channel_service()`` once at lifespan
+    # startup and the live channel clients are not rebuilt on
+    # config.yaml edits.
+    "channels": ("start_channel_service() is invoked once during startup; the live IM channel clients (Feishu, Slack, Telegram, DingTalk) are not rebuilt when channels.* changes."),
+}
+
+
+def iter_startup_only_field_paths() -> Iterator[str]:
+    """Yield every registered restart-required field path."""
+    return iter(STARTUP_ONLY_FIELDS)
+
+
+def is_startup_only_field(field_path: str) -> bool:
+    """Return ``True`` when *field_path* is registered as restart-required.
+
+    Accepts only top-level paths (``"database"``, ``"sandbox"`` etc.);
+    nested keys like ``"database.url"`` are not modelled here because the
+    boundary is per-section, not per-leaf.
+    """
+    return field_path in STARTUP_ONLY_FIELDS
+
+
+def format_field_description(field_path: str, *, field_doc: str | None = None) -> str:
+    """Build the standardised description for a registered field.
+
+    Used inside ``AppConfig`` ``Field(description=...)`` so the hover
+    text in IDEs matches the registry and the drift tests can pin one
+    side against the other.
+
+    Args:
+        field_path: A registered top-level field path (e.g. ``"log_level"``).
+        field_doc: Optional human-facing description for the field itself
+            (allowed values, semantics, etc.). When supplied, it is
+            appended after the ``startup-only:`` marker block separated by
+            a blank line so IDE hover shows both the restart-required
+            reason *and* the field's normal documentation. Composition
+            keeps the marker as the leading token machine-readable tooling
+            pivots on while restoring the prose that ``Field(description=)``
+            used to carry before the registry took over.
+
+    Raises:
+        KeyError: when *field_path* is not registered. This is deliberate
+            — silently returning a placeholder would let a typo bypass
+            the drift coverage.
+    """
+    reason = STARTUP_ONLY_FIELDS[field_path]
+    header = f"{STARTUP_ONLY_PREFIX} {reason}"
+    if field_doc is None:
+        return header
+    return f"{header}\n\n{field_doc.strip()}"
@@ -0,0 +1,62 @@
+"""Configuration for tool output budget protection."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class ToolOutputConfig(BaseModel):
+    """Config section for tool-result output budget enforcement.
+
+    When a tool returns more than ``externalize_min_chars`` characters,
+    the full output is persisted to disk and replaced with a compact
+    preview + file reference.  If disk persistence is unavailable the
+    output falls back to head+tail truncation.
+    """
+
+    enabled: bool = Field(
+        default=True,
+        description="Enable the tool output budget middleware.",
+    )
+    externalize_min_chars: int = Field(
+        default=12_000,
+        ge=0,
+        description="Character threshold to trigger disk externalization. Outputs below this pass through unchanged. Set to 0 to disable externalization (fallback truncation still applies when output exceeds fallback_max_chars).",
+    )
+    preview_head_chars: int = Field(
+        default=2_000,
+        ge=0,
+        description="Characters to keep from the head of the output in the preview.",
+    )
+    preview_tail_chars: int = Field(
+        default=1_000,
+        ge=0,
+        description="Characters to keep from the tail of the output in the preview.",
+    )
+    fallback_max_chars: int = Field(
+        default=30_000,
+        ge=0,
+        description="Maximum characters when disk persistence is unavailable. 0 disables fallback truncation.",
+    )
+    fallback_head_chars: int = Field(
+        default=8_000,
+        ge=0,
+        description="Head characters for fallback truncation.",
+    )
+    fallback_tail_chars: int = Field(
+        default=3_000,
+        ge=0,
+        description="Tail characters for fallback truncation.",
+    )
+    storage_subdir: str = Field(
+        default=".tool-results",
+        description="Subdirectory under the thread outputs path for persisted tool results.",
+    )
+    exempt_tools: list[str] = Field(
+        default_factory=lambda: ["read_file", "read_file_tool"],
+        description="Tool names exempt from budget enforcement (prevents persist→read→persist loops).",
+    )
+    tool_overrides: dict[str, int] = Field(
+        default_factory=dict,
+        description="Per-tool externalize_min_chars overrides. Keys are tool names, values are char thresholds. Use 0 to disable externalization for a specific tool.",
+    )
@@ -1,6 +1,10 @@
 """MCP (Model Context Protocol) integration using langchain-mcp-adapters."""

-from .cache import get_cached_mcp_tools, initialize_mcp_tools, reset_mcp_tools_cache
+from .cache import (
+    get_cached_mcp_tools,
+    initialize_mcp_tools,
+    reset_mcp_tools_cache,
+)
 from .client import build_server_params, build_servers_config
 from .tools import get_mcp_tools

@@ -87,8 +87,7 @@ def get_cached_mcp_tools() -> list[BaseTool]:

    Also checks if the config file has been modified since last initialization,
    and re-initializes if needed. This ensures that changes made through the
-    Gateway API (which runs in a separate process) are reflected in the
-    LangGraph Server.
+    Gateway API are reflected in the Gateway-embedded LangGraph runtime.

    Returns:
        List of cached MCP tools.
@@ -144,11 +143,20 @@ def reset_mcp_tools_cache() -> None:

    # Close persistent sessions – they will be recreated by the next
    # get_mcp_tools() call with the (possibly updated) connection config.
+    #
+    # close_all_sync() already picks the correct strategy per owning loop:
+    #   * sessions owned by the *current* running loop are only *signalled*
+    #     (their owner task runs __aexit__ once the loop regains control –
+    #     this is correct and leak-free, since the loop keeps the task alive),
+    #   * sessions on other threads' loops are torn down deterministically,
+    #   * idle/closed loops are handled or skipped.
+    # We deliberately do NOT try to synchronously wait for the current running
+    # loop to finish teardown here: that is a self-deadlock (the loop can only
+    # run the teardown after this synchronous call returns control to it).
    try:
        from deerflow.mcp.session_pool import get_session_pool

-        pool = get_session_pool()
-        pool.close_all_sync()
+        get_session_pool().close_all_sync()
    except Exception:
        logger.debug("Could not close MCP session pool on cache reset", exc_info=True)

@@ -8,6 +8,27 @@ This module provides a session pool that maintains persistent MCP sessions,
 scoped by ``(server_name, scope_key)`` — typically scope_key is the thread_id —
 so that consecutive tool calls share the same session and server-side state.
 Sessions are evicted in LRU order when the pool reaches capacity.
+
+Lifecycle model (owner task)
+----------------------------
+An MCP ``ClientSession`` is implemented on top of an ``anyio`` task group, and
+anyio enforces that a cancel scope must be exited from the *same task* that
+entered it. Calling ``cm.__aexit__`` from any task other than the one that ran
+``cm.__aenter__`` raises::
+
+    RuntimeError: Attempted to exit cancel scope in a different task than it
+    was entered in
+
+The sync-tool path (``make_sync_tool_wrapper``) drives each call through a fresh
+``asyncio.run`` event loop, so a session entered while answering one call would
+otherwise be exited while answering another — from a different task — and crash
+(GitHub issue #3379).
+
+To make this impossible, every pooled session is owned by a dedicated
+``_run_session`` task. That task enters the context manager, hands the live
+session back to the caller, and then *waits* on a close event. All shutdown
+paths only ever **signal** that event; the owner task performs ``__aexit__``
+itself, guaranteeing enter and exit always happen in the same task.
 """

 from __future__ import annotations
@@ -27,18 +48,81 @@ class MCPSessionPool:
    """Manages persistent MCP sessions scoped by ``(server_name, scope_key)``."""

    MAX_SESSIONS = 256
-    SESSION_CLOSE_TIMEOUT = 5.0  # seconds to wait when closing a session via run_coroutine_threadsafe
+    SESSION_CLOSE_TIMEOUT = 5.0  # seconds to wait when closing a session on a foreign loop

    def __init__(self) -> None:
+        # Each entry: (session, owning_loop, owner_task, close_event).
        self._entries: OrderedDict[
            tuple[str, str],
-            tuple[ClientSession, asyncio.AbstractEventLoop],
+            tuple[
+                ClientSession,
+                asyncio.AbstractEventLoop,
+                asyncio.Task[Any],
+                asyncio.Event,
+            ],
        ] = OrderedDict()
-        self._context_managers: dict[tuple[str, str], Any] = {}
+        # In-flight creations, keyed by (server, scope). Lets concurrent callers
+        # on the same loop share a single creation instead of each spawning a
+        # duplicate session. Value: (loop, ready_future, owner_task, close_event).
+        self._inflight: dict[
+            tuple[str, str],
+            tuple[
+                asyncio.AbstractEventLoop,
+                asyncio.Future[ClientSession],
+                asyncio.Task[Any],
+                asyncio.Event,
+            ],
+        ] = {}
        # threading.Lock is not bound to any event loop, so it is safe to
        # acquire from both async paths and sync/worker-thread paths.
        self._lock = threading.Lock()

+    # ------------------------------------------------------------------
+    # Session owner task
+    # ------------------------------------------------------------------
+
+    async def _run_session(
+        self,
+        connection: dict[str, Any],
+        ready: asyncio.Future[ClientSession],
+        close_evt: asyncio.Event,
+    ) -> None:
+        """Own a single MCP session for its entire lifetime.
+
+        Enters the session context manager, initializes it, publishes the live
+        session via ``ready``, then blocks until ``close_evt`` is set. The
+        context manager is *always* exited from this task, satisfying anyio's
+        cancel-scope same-task requirement.
+        """
+        from langchain_mcp_adapters.sessions import create_session
+
+        cm = create_session(connection)
+        try:
+            session = await cm.__aenter__()
+        except BaseException as e:
+            # Never entered the cancel scope, so there is nothing to exit.
+            if not ready.done():
+                ready.set_exception(e)
+            return
+
+        # The context manager is now entered. From here on __aexit__ MUST run in
+        # this task — on init failure, on cancellation, or on the close signal —
+        # to satisfy anyio's same-task cancel-scope requirement and to avoid
+        # leaking the session/subprocess.
+        try:
+            await session.initialize()
+            if not ready.done():
+                ready.set_result(session)
+            await close_evt.wait()
+        except BaseException as e:
+            if not ready.done():
+                ready.set_exception(e)
+        finally:
+            try:
+                await cm.__aexit__(None, None, None)
+            except Exception:
+                logger.warning("Error closing MCP session", exc_info=True)
+
    async def get_session(
        self,
        server_name: str,
@@ -47,9 +131,9 @@ class MCPSessionPool:
    ) -> ClientSession:
        """Get or create a persistent MCP session.

-        If an existing session was created in a different event loop (e.g.
-        the sync-wrapper path), it is closed and replaced with a fresh one
-        in the current loop.
+        If an existing session was created in a different (or closed) event
+        loop, it is evicted and replaced with a fresh one owned by a task on
+        the current loop.

        Args:
            server_name: MCP server name.
@@ -63,44 +147,118 @@ class MCPSessionPool:
        current_loop = asyncio.get_running_loop()

        # Phase 1: inspect/mutate the registry under the thread lock (no awaits).
-        cms_to_close: list[tuple[tuple[str, str], Any]] = []
+        # Decide one of three outcomes atomically: return an existing session,
+        # join an in-flight creation, or become the creator for this key.
+        # Each item: (loop, owner_task, close_event, cancel). ``cancel`` is True
+        # for in-flight creations, whose owner may be blocked inside
+        # ``initialize()`` where close_evt cannot wake it — it must be cancelled.
+        evicted: list[tuple[asyncio.AbstractEventLoop, asyncio.Task[Any], asyncio.Event, bool]] = []
+        join: asyncio.Future[ClientSession] | None = None
+        ready: asyncio.Future[ClientSession] | None = None
+        close_evt: asyncio.Event | None = None
+        task: asyncio.Task[Any] | None = None
        with self._lock:
            if key in self._entries:
-                session, loop = self._entries[key]
-                if loop is current_loop:
+                session, loop, ent_task, ent_close = self._entries[key]
+                if loop is current_loop and not loop.is_closed():
                    self._entries.move_to_end(key)
                    return session
-                # Session belongs to a different event loop – evict it.
-                cm = self._context_managers.pop(key, None)
+                # Session belongs to a different/closed event loop – evict it.
                self._entries.pop(key)
-                if cm is not None:
-                    cms_to_close.append((key, cm))
+                evicted.append((loop, ent_task, ent_close, False))
+
+            inflight = self._inflight.get(key)
+            if inflight is not None and inflight[0] is current_loop and not inflight[0].is_closed():
+                # Another caller on this loop is already creating the session;
+                # wait for the same result instead of building a duplicate.
+                join = inflight[1]
+            else:
+                if inflight is not None:
+                    # Stale in-flight creation owned by a different/closed loop.
+                    # Drop the record and tear its owner down; because that owner
+                    # may be blocked inside initialize() (where close_evt cannot
+                    # wake it), it must be cancelled. We then create a fresh
+                    # session here.
+                    self._inflight.pop(key)
+                    evicted.append((inflight[0], inflight[2], inflight[3], True))
+                # Become the creator: publish an in-flight record before any
+                # await so concurrent callers join us instead of racing.
+                ready = current_loop.create_future()
+                close_evt = asyncio.Event()
+                task = current_loop.create_task(self._run_session(connection, ready, close_evt))
+                self._inflight[key] = (current_loop, ready, task, close_evt)

            # Evict LRU entries when at capacity.
            while len(self._entries) >= self.MAX_SESSIONS:
-                oldest_key = next(iter(self._entries))
-                cm = self._context_managers.pop(oldest_key, None)
+                oldest_key, (_, loop, ent_task, ent_close) = next(iter(self._entries.items()))
                self._entries.pop(oldest_key)
-                if cm is not None:
-                    cms_to_close.append((oldest_key, cm))
+                evicted.append((loop, ent_task, ent_close, False))

-        # Phase 2: async cleanup outside the lock so we never await while holding it.
-        for close_key, cm in cms_to_close:
+        # Phase 2: shut down evicted sessions/creations. Same-loop owners are
+        # awaited so they finish deterministically; foreign-loop owners are
+        # routed to their own loop. In every case the owner task — never this
+        # one — runs __aexit__. In-flight owners are cancelled (cancel=True) so a
+        # blocking initialize() cannot leave them hung.
+        for loop, ent_task, ent_close, cancel in evicted:
+            if loop is current_loop and not loop.is_closed():
+                await self._shutdown(ent_close, ent_task, cancel)
+            elif cancel:
+                await self._shutdown_entry(loop, ent_task, ent_close, cancel=True)
+            else:
+                self._signal_close(loop, ent_close)
+
+        # Phase 2b: a concurrent creation for this key is already in progress on
+        # this loop — share its result rather than create a duplicate session.
+        if join is not None:
+            return await asyncio.shield(join)
+
+        assert ready is not None and close_evt is not None and task is not None
+
+        # Phase 3: wait for our owner task to publish the initialized session.
+        try:
+            session = await asyncio.shield(ready)
+        except BaseException:
+            # Two distinct cases reach here:
+            #
+            # 1. The owner task failed (e.g. connect/initialize error) and
+            #    reported it via ready.set_exception(). It is *already* in its
+            #    finally block running cm.__aexit__ in its own task, so we must
+            #    NOT cancel it — doing so would interrupt that cleanup. We only
+            #    wait for it to finish unwinding.
+            # 2. This call itself was cancelled (CancelledError). Because of the
+            #    shield, `ready` is still pending and the owner task is alive and
+            #    blocked. We signal close and cancel it so it exits the cancel
+            #    scope in its own task, then wait for it to finish.
+            #
+            # The session is never registered yet, so nobody else can close it;
+            # waiting here guarantees we never leak a session or owner task.
+            owner_already_failed = ready.done() and not ready.cancelled() and ready.exception() is not None
+            if not owner_already_failed:
+                close_evt.set()
+                task.cancel()
            try:
-                await cm.__aexit__(None, None, None)
-            except Exception:
-                logger.warning("Error closing MCP session %s", close_key, exc_info=True)
+                await asyncio.shield(task)
+            except BaseException:
+                logger.debug("Owner task ended during get_session unwind", exc_info=True)
+            with self._lock:
+                if self._inflight.get(key) == (current_loop, ready, task, close_evt):
+                    self._inflight.pop(key)
+            raise

-        from langchain_mcp_adapters.sessions import create_session
-
-        cm = create_session(connection)
-        session = await cm.__aenter__()
-        await session.initialize()
-
-        # Phase 3: register the new session under the lock.
+        # Phase 4: promote the in-flight creation to a registered entry — but
+        # only if our in-flight record is still the live one. A concurrent
+        # close_* / close_all may have removed it while we were initializing; in
+        # that case we must NOT resurrect the session into _entries. Instead we
+        # own the teardown: signal our owner task and wait for it to run
+        # __aexit__ in its own task, then surface the cancellation.
        with self._lock:
-            self._entries[key] = (session, current_loop)
-            self._context_managers[key] = cm
+            still_ours = self._inflight.get(key) == (current_loop, ready, task, close_evt)
+            if still_ours:
+                self._inflight.pop(key)
+                self._entries[key] = (session, current_loop, task, close_evt)
+        if not still_ours:
+            await self._shutdown(close_evt, task)
+            raise asyncio.CancelledError("MCP session pool was closed while the session was being created")
        logger.info("Created persistent MCP session for %s/%s", server_name, scope_key)
        return session

@@ -108,70 +266,169 @@ class MCPSessionPool:
    # Cleanup helpers
    # ------------------------------------------------------------------

-    async def _close_cm(self, key: tuple[str, str], cm: Any) -> None:
-        """Close a single context manager (must be called WITHOUT the lock)."""
+    @staticmethod
+    def _signal_close(loop: asyncio.AbstractEventLoop, close_evt: asyncio.Event) -> None:
+        """Ask an owner task to shut down without waiting.
+
+        ``asyncio.Event.set`` is not thread-safe, so it is scheduled on the
+        owning loop. A closed loop means the owner task is already gone.
+        """
+        if loop.is_closed():
+            return
        try:
-            await cm.__aexit__(None, None, None)
-        except Exception:
-            logger.warning("Error closing MCP session %s", key, exc_info=True)
+            loop.call_soon_threadsafe(close_evt.set)
+        except RuntimeError:
+            # Loop was closed between the is_closed() check and now.
+            pass
+
+    async def _shutdown(
+        self,
+        close_evt: asyncio.Event,
+        task: asyncio.Task[Any],
+        cancel: bool = False,
+    ) -> None:
+        """Signal an owner task and wait for it to finish (runs on its loop).
+
+        ``cancel=True`` is used for in-flight creations: the owner task may be
+        blocked inside ``initialize()`` where ``close_evt`` cannot wake it, so it
+        must be cancelled. Its ``finally`` block still runs ``__aexit__`` in its
+        own task, satisfying anyio's same-task cancel-scope requirement.
+        """
+        close_evt.set()
+        if cancel:
+            task.cancel()
+        try:
+            await task
+        except (Exception, asyncio.CancelledError):
+            logger.debug("Owner task ended during shutdown", exc_info=True)
+
+    async def _shutdown_entry(
+        self,
+        loop: asyncio.AbstractEventLoop,
+        task: asyncio.Task[Any],
+        close_evt: asyncio.Event,
+        cancel: bool = False,
+    ) -> None:
+        """Shut down one entry, routing the close to its owning loop."""
+        if loop.is_closed():
+            return
+        current_loop = asyncio.get_running_loop()
+        if loop is current_loop:
+            await self._shutdown(close_evt, task, cancel)
+        elif loop.is_running():
+            future = asyncio.run_coroutine_threadsafe(self._shutdown(close_evt, task, cancel), loop)
+            try:
+                await asyncio.wrap_future(future)
+            except Exception:
+                logger.warning("Error closing MCP session on owning loop", exc_info=True)
+        else:
+            # Owning loop exists but is neither the current loop nor running.
+            # We are inside an async context here, so run_until_complete() would
+            # raise "Cannot run the event loop while another loop is running";
+            # and the loop may belong to another thread, where driving it from
+            # here is unsafe. This branch is not expected in practice — a
+            # session's owning loop is either the long-lived gateway loop (which
+            # is running) or a short-lived asyncio.run loop (which is closed and
+            # caught above). Fall back to a best-effort thread-safe signal so the
+            # owner task tears down if/when its loop runs again.
+            logger.warning("Owning loop for MCP session is idle; signalling close best-effort. Session may leak until the loop runs again.")
+            self._signal_close(loop, close_evt)
+            if cancel:
+                try:
+                    loop.call_soon_threadsafe(task.cancel)
+                except RuntimeError:
+                    pass

    async def close_scope(self, scope_key: str) -> None:
        """Close all sessions for a given scope (e.g. thread_id)."""
        with self._lock:
            keys = [k for k in self._entries if k[1] == scope_key]
-            cms = [(k, self._context_managers.pop(k, None)) for k in keys]
-            for k in keys:
-                self._entries.pop(k, None)
-        for key, cm in cms:
-            if cm is not None:
-                await self._close_cm(key, cm)
+            entries = [(self._entries.pop(k)) for k in keys]
+            inflight_keys = [k for k in self._inflight if k[1] == scope_key]
+            inflight = [self._inflight.pop(k) for k in inflight_keys]
+        for _session, loop, task, close_evt in entries:
+            await self._shutdown_entry(loop, task, close_evt)
+        for loop, _ready, task, close_evt in inflight:
+            await self._shutdown_entry(loop, task, close_evt, cancel=True)

    async def close_server(self, server_name: str) -> None:
        """Close all sessions for a given server."""
        with self._lock:
            keys = [k for k in self._entries if k[0] == server_name]
-            cms = [(k, self._context_managers.pop(k, None)) for k in keys]
-            for k in keys:
-                self._entries.pop(k, None)
-        for key, cm in cms:
-            if cm is not None:
-                await self._close_cm(key, cm)
+            entries = [(self._entries.pop(k)) for k in keys]
+            inflight_keys = [k for k in self._inflight if k[0] == server_name]
+            inflight = [self._inflight.pop(k) for k in inflight_keys]
+        for _session, loop, task, close_evt in entries:
+            await self._shutdown_entry(loop, task, close_evt)
+        for loop, _ready, task, close_evt in inflight:
+            await self._shutdown_entry(loop, task, close_evt, cancel=True)

    async def close_all(self) -> None:
        """Close every managed session."""
        with self._lock:
-            cms = list(self._context_managers.items())
-            self._context_managers.clear()
+            entries = list(self._entries.values())
            self._entries.clear()
-        for key, cm in cms:
-            await self._close_cm(key, cm)
+            inflight = list(self._inflight.values())
+            self._inflight.clear()
+        for _session, loop, task, close_evt in entries:
+            await self._shutdown_entry(loop, task, close_evt)
+        for loop, _ready, task, close_evt in inflight:
+            await self._shutdown_entry(loop, task, close_evt, cancel=True)

    def close_all_sync(self) -> None:
-        """Close all sessions using their owning event loops (synchronous).
+        """Close all sessions on their owning event loops (synchronous).

-        Each session is closed on the loop it was created in, avoiding
-        cross-loop resource leaks.  Safe to call from any thread without an
-        active event loop.
+        Each session is closed by its owner task on the loop it was created in,
+        avoiding cross-loop and cross-task errors. Safe to call from any thread
+        without an active event loop.
+
+        Closing semantics differ by where the owning loop runs:
+
+        * Owning loop is idle, or running on another thread — this call blocks
+          until teardown completes (or ``SESSION_CLOSE_TIMEOUT`` elapses).
+        * Owning loop is the one currently running on *this* thread — we cannot
+          block on it without deadlocking, so teardown is only *signalled* here
+          and completes asynchronously once control returns to that loop. The
+          caller must therefore keep that loop running afterwards; if it stops
+          the loop immediately, the owner task's ``__aexit__`` may not run. When
+          a deterministic close is required from inside a running loop, ``await
+          close_all()`` instead.
        """
        with self._lock:
-            entries = list(self._entries.items())
-            cms = dict(self._context_managers)
+            entries = list(self._entries.values())
            self._entries.clear()
-            self._context_managers.clear()
+            inflight = list(self._inflight.values())
+            self._inflight.clear()

-        for key, (_, loop) in entries:
-            cm = cms.get(key)
-            if cm is None or loop.is_closed():
+        # Entries are initialized (gentle close_evt path). In-flight creations
+        # may be blocked mid-init, so they are cancelled to unblock teardown.
+        owners = [(loop, task, close_evt, False) for _s, loop, task, close_evt in entries]
+        owners += [(loop, task, close_evt, True) for loop, _r, task, close_evt in inflight]
+        try:
+            current_running_loop = asyncio.get_running_loop()
+        except RuntimeError:
+            current_running_loop = None
+        for loop, task, close_evt, cancel in owners:
+            if loop.is_closed():
                continue
            try:
-                if loop.is_running():
-                    # Schedule on the owning loop from this (different) thread.
-                    future = asyncio.run_coroutine_threadsafe(cm.__aexit__(None, None, None), loop)
+                if loop is current_running_loop:
+                    # We are executing inside this loop's thread, so synchronously
+                    # waiting on run_coroutine_threadsafe(...).result() would
+                    # deadlock until timeout. Signal the owner task directly and
+                    # let it finish once this synchronous call returns control to
+                    # the running loop.
+                    close_evt.set()
+                    if cancel:
+                        task.cancel()
+                elif loop.is_running():
+                    # Schedule the shutdown on the owning loop from this thread.
+                    future = asyncio.run_coroutine_threadsafe(self._shutdown(close_evt, task, cancel), loop)
                    future.result(timeout=self.SESSION_CLOSE_TIMEOUT)
                else:
-                    loop.run_until_complete(cm.__aexit__(None, None, None))
+                    loop.run_until_complete(self._shutdown(close_evt, task, cancel))
            except Exception:
-                logger.debug("Error closing MCP session %s during sync close", key, exc_info=True)
+                logger.debug("Error closing MCP session during sync close", exc_info=True)


 # ------------------------------------------------------------------
@@ -1,8 +1,9 @@
-"""Load MCP tools using langchain-mcp-adapters with persistent sessions."""
+"""Load MCP tools using langchain-mcp-adapters with stdio session pooling."""

 from __future__ import annotations

 import logging
+from collections.abc import Mapping
 from typing import Any

 from langchain_core.tools import BaseTool, StructuredTool
@@ -137,7 +138,15 @@ def _make_session_pool_tool(
            from langchain_mcp_adapters.interceptors import MCPToolCallRequest

            async def base_handler(request: MCPToolCallRequest) -> Any:
-                return await session.call_tool(request.name, request.args)
+                # Preserve interceptor-injected headers for stdio MCP calls by
+                # forwarding them through MCP call meta.
+                call_kwargs: dict[str, Any] = {}
+                if request.headers:
+                    if isinstance(request.headers, Mapping):
+                        call_kwargs["meta"] = {"headers": dict(request.headers)}
+                    else:
+                        logger.warning("Ignoring MCP interceptor headers with unsupported type: %s", type(request.headers).__name__)
+                return await session.call_tool(request.name, request.args, **call_kwargs)

            handler = base_handler
            for interceptor in reversed(tool_interceptors):
@@ -173,8 +182,10 @@ def _make_session_pool_tool(
 async def get_mcp_tools() -> list[BaseTool]:
    """Get all tools from enabled MCP servers.

-    Tools are wrapped with persistent-session logic so that consecutive
-    calls within the same thread reuse the same MCP session.
+    Tools using stdio transport are wrapped with persistent-session logic so
+    consecutive calls within the same thread reuse the same MCP session.
+    HTTP/SSE tools are returned unwrapped to avoid cross-task TaskGroup
+    cleanup errors.

    Returns:
        List of LangChain tools from all enabled MCP servers.
@@ -251,6 +262,9 @@ async def get_mcp_tools() -> list[BaseTool]:
        logger.info(f"Successfully loaded {len(tools)} tool(s) from MCP servers")

        # Wrap each tool with persistent-session logic.
+        # Only pool stdio sessions. HTTP/SSE transports use anyio TaskGroups
+        # internally which cannot be closed from a different async task, so
+        # pooling them causes RuntimeError on cleanup (see #3203).
        wrapped_tools: list[BaseTool] = []
        for tool in tools:
            tool_server: str | None = None
@@ -260,7 +274,11 @@ async def get_mcp_tools() -> list[BaseTool]:
                    break

            if tool_server is not None:
-                wrapped_tools.append(_make_session_pool_tool(tool, tool_server, servers_config[tool_server], tool_interceptors))
+                transport = servers_config[tool_server].get("transport", "stdio")
+                if transport == "stdio":
+                    wrapped_tools.append(_make_session_pool_tool(tool, tool_server, servers_config[tool_server], tool_interceptors))
+                else:
+                    wrapped_tools.append(tool)
            else:
                wrapped_tools.append(tool)

@@ -0,0 +1,124 @@
+"""Helpers for replaying provider-specific assistant message fields.
+
+Several provider adapters need to preserve fields that LangChain stores on the
+original ``AIMessage`` but drops when serializing request payloads. This module
+keeps the assistant-message matching logic shared while letting each provider
+decide which fields to restore.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable, Sequence
+from typing import Any
+
+from langchain_core.messages import AIMessage, BaseMessage
+
+AssistantPayloadRestorer = Callable[[dict[str, Any], AIMessage], None]
+
+
+def restore_assistant_payloads(
+    payload_messages: Sequence[dict[str, Any]],
+    original_messages: Sequence[BaseMessage],
+    restore: AssistantPayloadRestorer,
+) -> None:
+    """Restore provider-specific fields onto serialized assistant payloads."""
+    if len(payload_messages) == len(original_messages):
+        for payload_msg, orig_msg in zip(payload_messages, original_messages):
+            if payload_msg.get("role") == "assistant" and isinstance(orig_msg, AIMessage):
+                restore(payload_msg, orig_msg)
+        return
+
+    ai_messages = [m for m in original_messages if isinstance(m, AIMessage)]
+    assistant_payloads = [m for m in payload_messages if m.get("role") == "assistant"]
+    used_ai_indexes: set[int] = set()
+
+    for ordinal, payload_msg in enumerate(assistant_payloads):
+        ai_msg = _match_ai_message(payload_msg, ai_messages, used_ai_indexes, ordinal)
+        if ai_msg is not None:
+            restore(payload_msg, ai_msg)
+
+
+def restore_additional_kwargs_field(payload_msg: dict[str, Any], orig_msg: AIMessage, field_name: str) -> None:
+    """Copy a provider-specific ``additional_kwargs`` field onto a payload message."""
+    value = orig_msg.additional_kwargs.get(field_name)
+    if value is not None:
+        payload_msg[field_name] = value
+
+
+def restore_reasoning_content(payload_msg: dict[str, Any], orig_msg: AIMessage) -> None:
+    """Copy provider reasoning content onto a serialized assistant payload."""
+    restore_additional_kwargs_field(payload_msg, orig_msg, "reasoning_content")
+
+
+def _match_ai_message(
+    payload_msg: dict[str, Any],
+    ai_messages: Sequence[AIMessage],
+    used_ai_indexes: set[int],
+    fallback_ordinal: int,
+) -> AIMessage | None:
+    payload_key = _assistant_signature(payload_msg)
+    if payload_key is not None:
+        matches = [index for index, ai_msg in enumerate(ai_messages) if index not in used_ai_indexes and _ai_signature(ai_msg) == payload_key]
+        if len(matches) == 1:
+            used_ai_indexes.add(matches[0])
+            return ai_messages[matches[0]]
+
+    fallback_index = _next_unused_index_at_or_after(len(ai_messages), used_ai_indexes, fallback_ordinal)
+    if fallback_index is not None:
+        used_ai_indexes.add(fallback_index)
+        return ai_messages[fallback_index]
+
+    return None
+
+
+def _next_unused_index_at_or_after(count: int, used_ai_indexes: set[int], start: int) -> int | None:
+    """Return the next unused AI index at or after ``start``.
+
+    Scanning forward from the payload's ordinal preserves the positional bias of
+    the previous behaviour while still recovering when serialization drops or
+    reorders messages so the exact ordinal index is already taken. It does not
+    wrap to earlier indexes because those messages may be represented by payload
+    entries that were already dropped.
+    """
+    if count == 0 or start >= count:
+        return None
+    for index in range(start, count):
+        if index not in used_ai_indexes:
+            return index
+    return None
+
+
+def _assistant_signature(payload_msg: dict[str, Any]) -> tuple[str, str] | None:
+    return _signature(
+        payload_msg.get("content"),
+        _tool_call_ids(payload_msg.get("tool_calls") or []),
+    )
+
+
+def _ai_signature(message: AIMessage) -> tuple[str, str] | None:
+    tool_calls = message.tool_calls or message.additional_kwargs.get("tool_calls") or []
+    return _signature(message.content, _tool_call_ids(tool_calls))
+
+
+def _signature(content: Any, tool_call_ids: tuple[str, ...]) -> tuple[str, str] | None:
+    if content in (None, "") and not tool_call_ids:
+        return None
+    return (_stable_repr(content), "|".join(tool_call_ids))
+
+
+def _stable_repr(value: Any) -> str:
+    try:
+        return json.dumps(value, sort_keys=True, ensure_ascii=False)
+    except TypeError:
+        return repr(value)
+
+
+def _tool_call_ids(tool_calls: Sequence[Any]) -> tuple[str, ...]:
+    ids: list[str] = []
+    for tool_call in tool_calls:
+        if isinstance(tool_call, dict):
+            call_id = tool_call.get("id")
+            if isinstance(call_id, str) and call_id:
+                ids.append(call_id)
+    return tuple(ids)
@@ -47,6 +47,38 @@ def _enable_stream_usage_by_default(model_use_path: str, model_settings_from_con
        model_settings_from_config["stream_usage"] = True


+# Default chunk-gap budget for OpenAI-compatible streaming responses.
+#
+# langchain-openai raises ``StreamChunkTimeoutError`` after this many seconds
+# without receiving a chunk. Its own default is 60s, which is too aggressive for
+# reasoning models (DeepSeek-R1, Doubao-thinking, GPT-5) whose first chunk can
+# legitimately take 90~150s. We default to 240s so the streaming layer rarely
+# trips on long thinking pauses; the LLMErrorHandlingMiddleware still retries
+# (budget=2) if a real stall happens. Users can override per-model in config.yaml.
+_DEFAULT_STREAM_CHUNK_TIMEOUT_SECONDS: float = 240.0
+
+
+def _apply_stream_chunk_timeout_default(model_use_path: str, model_settings_from_config: dict) -> None:
+    """Inject a generous ``stream_chunk_timeout`` for OpenAI-compatible clients.
+
+    The ``stream_chunk_timeout`` kwarg is specific to ``langchain_openai:ChatOpenAI``
+    and is rejected by other providers' constructors as an unexpected keyword
+    argument. Behaviour:
+
+    * OpenAI-compatible path: an explicit value in ``config.yaml`` is preserved.
+      An explicit ``null`` is dropped upstream by ``model_dump(exclude_none=True)``
+      and therefore treated as "unset", so the default is injected.
+    * Non-OpenAI path: drop the key so it is never forwarded to an incompatible
+      constructor (which would raise ``TypeError: unexpected keyword argument``).
+    """
+    if model_use_path != "langchain_openai:ChatOpenAI":
+        model_settings_from_config.pop("stream_chunk_timeout", None)
+        return
+    if "stream_chunk_timeout" in model_settings_from_config:
+        return
+    model_settings_from_config["stream_chunk_timeout"] = _DEFAULT_STREAM_CHUNK_TIMEOUT_SECONDS
+
+
 def create_chat_model(name: str | None = None, thinking_enabled: bool = False, *, app_config: AppConfig | None = None, attach_tracing: bool = True, **kwargs) -> BaseChatModel:
    """Create a chat model instance from the config.

@@ -128,6 +160,7 @@ def create_chat_model(name: str | None = None, thinking_enabled: bool = False, *
        model_settings_from_config.pop("reasoning_effort", None)

    _enable_stream_usage_by_default(model_config.use, model_settings_from_config)
+    _apply_stream_chunk_timeout_default(model_config.use, model_settings_from_config)

    # For Codex Responses API models: map thinking mode to reasoning_effort
    from deerflow.models.openai_codex_provider import CodexChatModel
@@ -10,9 +10,10 @@ on all assistant messages when thinking mode is enabled.
 from typing import Any

 from langchain_core.language_models import LanguageModelInput
-from langchain_core.messages import AIMessage
 from langchain_deepseek import ChatDeepSeek

+from deerflow.models.assistant_payload_replay import restore_assistant_payloads, restore_reasoning_content
+

 class PatchedChatDeepSeek(ChatDeepSeek):
    """ChatDeepSeek with proper reasoning_content preservation.
@@ -49,25 +50,10 @@ class PatchedChatDeepSeek(ChatDeepSeek):
        # Call parent to get the base payload
        payload = super()._get_request_payload(input_, stop=stop, **kwargs)

-        # Match payload messages with original messages to restore reasoning_content
-        payload_messages = payload.get("messages", [])
-
-        # The payload messages and original messages should be in the same order
-        # Iterate through both and match by position
-        if len(payload_messages) == len(original_messages):
-            for payload_msg, orig_msg in zip(payload_messages, original_messages):
-                if payload_msg.get("role") == "assistant" and isinstance(orig_msg, AIMessage):
-                    reasoning_content = orig_msg.additional_kwargs.get("reasoning_content")
-                    if reasoning_content is not None:
-                        payload_msg["reasoning_content"] = reasoning_content
-        else:
-            # Fallback: match by counting assistant messages
-            ai_messages = [m for m in original_messages if isinstance(m, AIMessage)]
-            assistant_payloads = [(i, m) for i, m in enumerate(payload_messages) if m.get("role") == "assistant"]
-
-            for (idx, payload_msg), ai_msg in zip(assistant_payloads, ai_messages):
-                reasoning_content = ai_msg.additional_kwargs.get("reasoning_content")
-                if reasoning_content is not None:
-                    payload_messages[idx]["reasoning_content"] = reasoning_content
+        restore_assistant_payloads(
+            payload.get("messages", []),
+            original_messages,
+            restore_reasoning_content,
+        )

        return payload
@@ -0,0 +1,140 @@
+"""Patched ChatOpenAI adapter for Xiaomi MiMo reasoning_content replay.
+
+MiMo's OpenAI-compatible API returns ``reasoning_content`` in thinking mode and
+requires that value to be replayed on historical assistant messages in
+multi-turn agent conversations. Standard ``langchain_openai.ChatOpenAI`` drops
+that provider-specific field, which can cause HTTP 400 errors once tool calls
+enter the conversation history.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from langchain_core.language_models import LanguageModelInput
+from langchain_core.messages import AIMessage, AIMessageChunk
+from langchain_core.outputs import ChatGeneration, ChatGenerationChunk, ChatResult
+from langchain_openai import ChatOpenAI
+
+from deerflow.models.assistant_payload_replay import restore_assistant_payloads, restore_reasoning_content
+
+_MISSING = object()
+
+
+def _extract_reasoning_content(value: Any) -> str | object:
+    """Return reasoning_content from a dict/Pydantic object, preserving empty strings."""
+    if isinstance(value, Mapping):
+        if "reasoning_content" in value and value["reasoning_content"] is not None:
+            return value["reasoning_content"]
+        return _MISSING
+
+    reasoning = getattr(value, "reasoning_content", _MISSING)
+    if reasoning is not _MISSING and reasoning is not None:
+        return reasoning
+
+    model_extra = getattr(value, "model_extra", None)
+    if isinstance(model_extra, Mapping) and "reasoning_content" in model_extra and model_extra["reasoning_content"] is not None:
+        return model_extra["reasoning_content"]
+
+    return _MISSING
+
+
+def _with_reasoning_content(message: AIMessage | AIMessageChunk, reasoning: str) -> AIMessage | AIMessageChunk:
+    additional_kwargs = dict(message.additional_kwargs)
+    if additional_kwargs.get("reasoning_content") != reasoning:
+        additional_kwargs["reasoning_content"] = reasoning
+    return message.model_copy(update={"additional_kwargs": additional_kwargs})
+
+
+def _get_typed_choice_message(response: Any, index: int) -> Any:
+    choices = getattr(response, "choices", None)
+    if choices is None:
+        return None
+    try:
+        return choices[index].message
+    except (AttributeError, IndexError, TypeError):
+        return None
+
+
+class PatchedChatMiMo(ChatOpenAI):
+    """ChatOpenAI with ``reasoning_content`` preservation for MiMo thinking mode."""
+
+    @classmethod
+    def is_lc_serializable(cls) -> bool:
+        return True
+
+    @property
+    def lc_secrets(self) -> dict[str, str]:
+        return {"api_key": "MIMO_API_KEY", "openai_api_key": "MIMO_API_KEY"}
+
+    def _get_request_payload(
+        self,
+        input_: LanguageModelInput,
+        *,
+        stop: list[str] | None = None,
+        **kwargs: Any,
+    ) -> dict:
+        original_messages = self._convert_input(input_).to_messages()
+        payload = super()._get_request_payload(input_, stop=stop, **kwargs)
+        restore_assistant_payloads(
+            payload.get("messages", []),
+            original_messages,
+            restore_reasoning_content,
+        )
+
+        return payload
+
+    def _convert_chunk_to_generation_chunk(
+        self,
+        chunk: dict,
+        default_chunk_class: type,
+        base_generation_info: dict | None,
+    ) -> ChatGenerationChunk | None:
+        generation_chunk = super()._convert_chunk_to_generation_chunk(
+            chunk,
+            default_chunk_class,
+            base_generation_info,
+        )
+        if generation_chunk is None:
+            return None
+
+        choices = chunk.get("choices", [])
+        if choices:
+            delta = choices[0].get("delta") or {}
+            reasoning = _extract_reasoning_content(delta)
+            if reasoning is not _MISSING and isinstance(generation_chunk.message, AIMessageChunk):
+                generation_chunk = ChatGenerationChunk(
+                    message=_with_reasoning_content(generation_chunk.message, reasoning),
+                    generation_info=generation_chunk.generation_info,
+                )
+
+        return generation_chunk
+
+    def _create_chat_result(
+        self,
+        response: dict | Any,
+        generation_info: dict | None = None,
+    ) -> ChatResult:
+        result = super()._create_chat_result(response, generation_info)
+        response_dict = response if isinstance(response, dict) else response.model_dump()
+        choices = response_dict.get("choices", [])
+
+        patched_generations: list[ChatGeneration] | None = None
+        for index, generation in enumerate(result.generations):
+            choice = choices[index] if index < len(choices) else {}
+            choice_message = choice.get("message", {}) if isinstance(choice, Mapping) else {}
+            reasoning = _extract_reasoning_content(choice_message)
+            if reasoning is _MISSING and not isinstance(response, dict):
+                reasoning = _extract_reasoning_content(_get_typed_choice_message(response, index))
+
+            message = generation.message
+            if reasoning is not _MISSING and isinstance(message, AIMessage):
+                if patched_generations is None:
+                    patched_generations = list(result.generations)
+                patched_generations[index] = ChatGeneration(
+                    message=_with_reasoning_content(message, reasoning),
+                    generation_info=generation.generation_info,
+                )
+
+        return ChatResult(generations=patched_generations or result.generations, llm_output=result.llm_output)
@@ -27,6 +27,8 @@ from langchain_core.language_models import LanguageModelInput
 from langchain_core.messages import AIMessage
 from langchain_openai import ChatOpenAI

+from deerflow.models.assistant_payload_replay import restore_assistant_payloads
+

 class PatchedChatOpenAI(ChatOpenAI):
    """ChatOpenAI with ``thought_signature`` preservation for Gemini thinking via OpenAI gateway.
@@ -75,18 +77,7 @@ class PatchedChatOpenAI(ChatOpenAI):
        # Obtain the base payload from the parent implementation.
        payload = super()._get_request_payload(input_, stop=stop, **kwargs)

-        payload_messages = payload.get("messages", [])
-
-        if len(payload_messages) == len(original_messages):
-            for payload_msg, orig_msg in zip(payload_messages, original_messages):
-                if payload_msg.get("role") == "assistant" and isinstance(orig_msg, AIMessage):
-                    _restore_tool_call_signatures(payload_msg, orig_msg)
-        else:
-            # Fallback: match assistant-role entries positionally against AIMessages.
-            ai_messages = [m for m in original_messages if isinstance(m, AIMessage)]
-            assistant_payloads = [(i, m) for i, m in enumerate(payload_messages) if m.get("role") == "assistant"]
-            for (_, payload_msg), ai_msg in zip(assistant_payloads, ai_messages):
-                _restore_tool_call_signatures(payload_msg, ai_msg)
+        restore_assistant_payloads(payload.get("messages", []), original_messages, _restore_tool_call_signatures)

        return payload

@@ -47,6 +47,41 @@ def _prepare_database_sqlite_checkpointer_path(db_config) -> str:
    return conn_str


+def _build_postgres_pool(conn_string: str):
+    """Build an AsyncConnectionPool with TCP keepalive and connection checking."""
+    from psycopg.rows import dict_row
+    from psycopg_pool import AsyncConnectionPool
+
+    return AsyncConnectionPool(
+        conn_string,
+        kwargs={
+            "autocommit": True,
+            "prepare_threshold": 0,
+            "row_factory": dict_row,
+            "keepalives": 1,
+            "keepalives_idle": 60,
+            "keepalives_interval": 10,
+            "keepalives_count": 6,
+        },
+        check=AsyncConnectionPool.check_connection,
+    )
+
+
+def _ensure_postgres_imports():
+    """Import and return (AsyncPostgresSaver, AsyncConnectionPool), raising ImportError on failure."""
+    try:
+        from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver
+    except ImportError as exc:
+        raise ImportError(POSTGRES_INSTALL) from exc
+
+    try:
+        from psycopg_pool import AsyncConnectionPool
+    except ImportError as exc:
+        raise ImportError(POSTGRES_INSTALL) from exc
+
+    return AsyncPostgresSaver, AsyncConnectionPool
+
+
 # ---------------------------------------------------------------------------
 # Async factory
 # ---------------------------------------------------------------------------
@@ -74,15 +109,13 @@ async def _async_checkpointer(config) -> AsyncIterator[Checkpointer]:
        return

    if config.type == "postgres":
-        try:
-            from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver
-        except ImportError as exc:
-            raise ImportError(POSTGRES_INSTALL) from exc
-
        if not config.connection_string:
            raise ValueError(POSTGRES_CONN_REQUIRED)

-        async with AsyncPostgresSaver.from_conn_string(config.connection_string) as saver:
+        AsyncPostgresSaver, _ = _ensure_postgres_imports()
+        pool = _build_postgres_pool(config.connection_string)
+        async with pool:
+            saver = AsyncPostgresSaver(conn=pool)
            await saver.setup()
            yield saver
        return
@@ -117,15 +150,13 @@ async def _async_checkpointer_from_database(db_config) -> AsyncIterator[Checkpoi
        return

    if db_config.backend == "postgres":
-        try:
-            from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver
-        except ImportError as exc:
-            raise ImportError(POSTGRES_INSTALL) from exc
-
        if not db_config.postgres_url:
            raise ValueError("database.postgres_url is required for the postgres backend")

-        async with AsyncPostgresSaver.from_conn_string(db_config.postgres_url) as saver:
+        AsyncPostgresSaver, _ = _ensure_postgres_imports()
+        pool = _build_postgres_pool(db_config.postgres_url)
+        async with pool:
+            saver = AsyncPostgresSaver(conn=pool)
            await saver.setup()
            yield saver
        return
@@ -144,10 +144,13 @@ class DbRunEventStore(RunEventStore):
    async def put_batch(self, events):
        if not events:
            return []
+        thread_ids = {e["thread_id"] for e in events}
+        if len(thread_ids) > 1:
+            raise ValueError(f"put_batch requires all events to belong to the same thread; got {thread_ids!r}")
        user_id = self._user_id_from_context()
        async with self._sf() as session:
            async with session.begin():
-                # Get max seq for the thread (assume all events in batch belong to same thread).
+                # All events belong to the same thread (validated above).
                thread_id = events[0]["thread_id"]
                max_seq = await self._max_seq_for_thread(session, thread_id)
                seq = max_seq or 0
@@ -6,6 +6,15 @@ Each run's events are stored in a single file:
 All categories (message, trace, lifecycle) are in the same file.
 This backend is suitable for lightweight single-node deployments.

+**Single-process guarantee**: the in-memory seq counter is process-local.
+Multi-process deployments sharing the same directory will produce duplicate
+or non-monotonic seq values. Use ``DbRunEventStore`` for multi-process or
+high-concurrency deployments.
+
+File I/O is offloaded to a thread pool via ``asyncio.to_thread`` so the
+event loop is never blocked. Per-thread ``asyncio.Lock`` objects serialise
+writes within a single process to prevent interleaved JSONL lines.
+
 Known trade-off: ``list_messages()`` must scan all run files for a
 thread since messages from multiple runs need unified seq ordering.
 ``list_events()`` reads only one file -- the fast path.
@@ -13,6 +22,7 @@ thread since messages from multiple runs need unified seq ordering.

 from __future__ import annotations

+import asyncio
 import json
 import logging
 import re
@@ -30,6 +40,11 @@ class JsonlRunEventStore(RunEventStore):
    def __init__(self, base_dir: str | Path | None = None):
        self._base_dir = Path(base_dir) if base_dir else Path(".deer-flow")
        self._seq_counters: dict[str, int] = {}  # thread_id -> current max seq
+        # Per-thread asyncio.Lock — serialises concurrent writes within one process.
+        self._write_locks: dict[str, asyncio.Lock] = {}
+
+    def _get_write_lock(self, thread_id: str) -> asyncio.Lock:
+        return self._write_locks.setdefault(thread_id, asyncio.Lock())

    @staticmethod
    def _validate_id(value: str, label: str) -> str:
@@ -50,10 +65,8 @@ class JsonlRunEventStore(RunEventStore):
        self._seq_counters[thread_id] = self._seq_counters.get(thread_id, 0) + 1
        return self._seq_counters[thread_id]

-    def _ensure_seq_loaded(self, thread_id: str) -> None:
-        """Load max seq from existing files if not yet cached."""
-        if thread_id in self._seq_counters:
-            return
+    def _compute_max_seq(self, thread_id: str) -> int:
+        """Scan all run files for a thread and return the current max seq (blocking I/O)."""
        max_seq = 0
        thread_dir = self._thread_dir(thread_id)
        if thread_dir.exists():
@@ -64,7 +77,13 @@ class JsonlRunEventStore(RunEventStore):
                        max_seq = max(max_seq, record.get("seq", 0))
                    except json.JSONDecodeError:
                        logger.debug("Skipping malformed JSONL line in %s", f)
-                        continue
+        return max_seq
+
+    async def _ensure_seq_loaded(self, thread_id: str) -> None:
+        """Load max seq from existing files into the in-memory counter (non-blocking)."""
+        if thread_id in self._seq_counters:
+            return
+        max_seq = await asyncio.to_thread(self._compute_max_seq, thread_id)
        self._seq_counters[thread_id] = max_seq

    def _write_record(self, record: dict) -> None:
@@ -74,7 +93,7 @@ class JsonlRunEventStore(RunEventStore):
            f.write(json.dumps(record, default=str, ensure_ascii=False) + "\n")

    def _read_thread_events(self, thread_id: str) -> list[dict]:
-        """Read all events for a thread, sorted by seq."""
+        """Read all events for a thread, sorted by seq (blocking I/O)."""
        events = []
        thread_dir = self._thread_dir(thread_id)
        if not thread_dir.exists():
@@ -87,12 +106,11 @@ class JsonlRunEventStore(RunEventStore):
                    events.append(json.loads(line))
                except json.JSONDecodeError:
                    logger.debug("Skipping malformed JSONL line in %s", f)
-                    continue
        events.sort(key=lambda e: e.get("seq", 0))
        return events

    def _read_run_events(self, thread_id: str, run_id: str) -> list[dict]:
-        """Read events for a specific run file."""
+        """Read events for a specific run file (blocking I/O)."""
        path = self._run_file(thread_id, run_id)
        if not path.exists():
            return []
@@ -104,25 +122,36 @@ class JsonlRunEventStore(RunEventStore):
                events.append(json.loads(line))
            except json.JSONDecodeError:
                logger.debug("Skipping malformed JSONL line in %s", path)
-                continue
        events.sort(key=lambda e: e.get("seq", 0))
        return events

+    def _delete_thread_files(self, thread_id: str) -> None:
+        thread_dir = self._thread_dir(thread_id)
+        if thread_dir.exists():
+            for f in thread_dir.glob("*.jsonl"):
+                f.unlink()
+
+    def _delete_run_file(self, thread_id: str, run_id: str) -> None:
+        path = self._run_file(thread_id, run_id)
+        if path.exists():
+            path.unlink()
+
    async def put(self, *, thread_id, run_id, event_type, category, content="", metadata=None, created_at=None):
-        self._ensure_seq_loaded(thread_id)
-        seq = self._next_seq(thread_id)
-        record = {
-            "thread_id": thread_id,
-            "run_id": run_id,
-            "event_type": event_type,
-            "category": category,
-            "content": content,
-            "metadata": metadata or {},
-            "seq": seq,
-            "created_at": created_at or datetime.now(UTC).isoformat(),
-        }
-        self._write_record(record)
-        return record
+        async with self._get_write_lock(thread_id):
+            await self._ensure_seq_loaded(thread_id)
+            seq = self._next_seq(thread_id)
+            record = {
+                "thread_id": thread_id,
+                "run_id": run_id,
+                "event_type": event_type,
+                "category": category,
+                "content": content,
+                "metadata": metadata or {},
+                "seq": seq,
+                "created_at": created_at or datetime.now(UTC).isoformat(),
+            }
+            await asyncio.to_thread(self._write_record, record)
+            return record

    async def put_batch(self, events):
        if not events:
@@ -134,7 +163,7 @@ class JsonlRunEventStore(RunEventStore):
        return results

    async def list_messages(self, thread_id, *, limit=50, before_seq=None, after_seq=None):
-        all_events = self._read_thread_events(thread_id)
+        all_events = await asyncio.to_thread(self._read_thread_events, thread_id)
        messages = [e for e in all_events if e.get("category") == "message"]

        if before_seq is not None:
@@ -147,13 +176,13 @@ class JsonlRunEventStore(RunEventStore):
            return messages[-limit:]

    async def list_events(self, thread_id, run_id, *, event_types=None, limit=500):
-        events = self._read_run_events(thread_id, run_id)
+        events = await asyncio.to_thread(self._read_run_events, thread_id, run_id)
        if event_types is not None:
            events = [e for e in events if e.get("event_type") in event_types]
        return events[:limit]

    async def list_messages_by_run(self, thread_id, run_id, *, limit=50, before_seq=None, after_seq=None):
-        events = self._read_run_events(thread_id, run_id)
+        events = await asyncio.to_thread(self._read_run_events, thread_id, run_id)
        filtered = [e for e in events if e.get("category") == "message"]
        if before_seq is not None:
            filtered = [e for e in filtered if e.get("seq", 0) < before_seq]
@@ -165,23 +194,25 @@ class JsonlRunEventStore(RunEventStore):
            return filtered[-limit:] if len(filtered) > limit else filtered

    async def count_messages(self, thread_id):
-        all_events = self._read_thread_events(thread_id)
+        all_events = await asyncio.to_thread(self._read_thread_events, thread_id)
        return sum(1 for e in all_events if e.get("category") == "message")

    async def delete_by_thread(self, thread_id):
-        all_events = self._read_thread_events(thread_id)
-        count = len(all_events)
-        thread_dir = self._thread_dir(thread_id)
-        if thread_dir.exists():
-            for f in thread_dir.glob("*.jsonl"):
-                f.unlink()
-        self._seq_counters.pop(thread_id, None)
-        return count
+        async with self._get_write_lock(thread_id):
+            all_events = await asyncio.to_thread(self._read_thread_events, thread_id)
+            count = len(all_events)
+            await asyncio.to_thread(self._delete_thread_files, thread_id)
+            self._seq_counters.pop(thread_id, None)
+            # Pop the lock inside the held scope to minimise the window where a new caller
+            # could obtain a fresh lock while a waiting coroutine still holds the old one.
+            # Note: coroutines that already acquired a reference to this lock before the
+            # delete will still proceed after we release — this is an accepted narrow race.
+            self._write_locks.pop(thread_id, None)
+            return count

    async def delete_by_run(self, thread_id, run_id):
-        events = self._read_run_events(thread_id, run_id)
-        count = len(events)
-        path = self._run_file(thread_id, run_id)
-        if path.exists():
-            path.unlink()
-        return count
+        async with self._get_write_lock(thread_id):
+            events = await asyncio.to_thread(self._read_run_events, thread_id, run_id)
+            count = len(events)
+            await asyncio.to_thread(self._delete_run_file, thread_id, run_id)
+            return count
@@ -86,6 +86,8 @@ class RunJournal(BaseCallbackHandler):
        self._last_ai_msg: str | None = None
        self._first_human_msg: str | None = None
        self._msg_count = 0
+        self._had_llm_error_fallback = False
+        self._llm_error_fallback_message: str | None = None

        # Latency tracking
        self._llm_start_times: dict[str, float] = {}  # langchain run_id -> start time
@@ -256,6 +258,18 @@ class RunJournal(BaseCallbackHandler):
            # Token usage from message
            usage = getattr(message, "usage_metadata", None)
            usage_dict = dict(usage) if usage else {}
+            additional_kwargs = getattr(message, "additional_kwargs", None) or {}
+            if isinstance(additional_kwargs, dict) and additional_kwargs.get("deerflow_error_fallback"):
+                self._had_llm_error_fallback = True
+                detail = additional_kwargs.get("error_detail")
+                reason = additional_kwargs.get("error_reason")
+                fallback_text = self._message_text(message).strip()
+                if isinstance(detail, str) and detail.strip():
+                    self._llm_error_fallback_message = detail.strip()
+                elif isinstance(reason, str) and reason.strip():
+                    self._llm_error_fallback_message = reason.strip()
+                elif fallback_text:
+                    self._llm_error_fallback_message = fallback_text[:2000]

            # Resolve call index
            call_index = self._llm_call_index
@@ -569,3 +583,11 @@ class RunJournal(BaseCallbackHandler):
            "last_ai_message": self._last_ai_msg,
            "first_human_message": self._first_human_msg,
        }
+
+    @property
+    def had_llm_error_fallback(self) -> bool:
+        return self._had_llm_error_fallback
+
+    @property
+    def llm_error_fallback_message(self) -> str | None:
+        return self._llm_error_fallback_message
@@ -645,6 +645,98 @@ class RunManager:
            self._runs.pop(run_id, None)
        logger.debug("Run record %s cleaned up", run_id)

+    async def shutdown(self, *, timeout: float = 5.0) -> None:
+        """Cancel and bounded-await all in-flight runs on process shutdown.
+
+        Chat runs execute in fire-and-forget background ``asyncio`` tasks that
+        write checkpoints through a shared checkpointer. On shutdown the
+        checkpointer's resources (e.g. the postgres connection pool owned by the
+        gateway's ``AsyncExitStack``) are torn down; if a run task is still
+        mid-graph at that point, langgraph's
+        ``AsyncPregelLoop._checkpointer_put_after_previous`` runs its
+        ``finally: await checkpointer.aput(...)`` against the closed pool. Because
+        that put runs in a langgraph-internal task (not on ``run_agent``'s call
+        stack), the resulting ``psycopg_pool.PoolClosed`` is not catchable by the
+        worker and surfaces as an unhandled exception during ``asyncio.run()``
+        shutdown (bytedance/deer-flow issue #3373).
+
+        Draining in-flight runs *before* the checkpointer is closed lets each
+        run that settles within ``timeout`` flush its final checkpoint while
+        resources are still open. Only runs that do **not** settle on their own
+        are marked ``interrupted`` — a run that completes (e.g. ``success``)
+        during the drain keeps its real terminal status instead of being
+        blanket-overwritten. The whole drain, including the trailing status
+        persistence, is bounded by ``timeout`` so a run stuck in cleanup (or a
+        slow store under DB pressure) cannot hang worker shutdown — the
+        precondition for the signal-reentrancy deadlock guarded by
+        ``app.gateway.app._SHUTDOWN_HOOK_TIMEOUT_SECONDS``. Runs still active
+        after ``timeout`` are logged and may still race teardown.
+        """
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + timeout
+
+        async with self._lock:
+            inflight = [record for record in self._runs.values() if record.status in (RunStatus.pending, RunStatus.running) and record.task is not None and not record.task.done()]
+            for record in inflight:
+                record.abort_action = "interrupt"
+                record.abort_event.set()
+                record.task.cancel()  # type: ignore[union-attr]  # filtered above
+                # Status is decided AFTER the drain (below), not here: a run that
+                # completes on its own during the drain must keep its real status.
+
+        if not inflight:
+            return
+
+        tasks = [record.task for record in inflight]
+        _, pending = await asyncio.wait(tasks, timeout=timeout)
+
+        # Only mark/persist ``interrupted`` for runs that did not settle on their
+        # own (still pending after the timeout, or ended cancelled). A run that
+        # finished normally during the drain keeps the status it set for itself.
+        to_persist: list[RunRecord] = []
+        async with self._lock:
+            for record in inflight:
+                task = record.task
+                if task not in pending and not task.cancelled():
+                    # Completed on its own — retrieve any surfaced exception so it
+                    # is not reported as "never retrieved", and keep its status.
+                    task.exception()  # type: ignore[union-attr]  # done & not cancelled
+                    continue
+                if record.status in (RunStatus.pending, RunStatus.running):
+                    record.status = RunStatus.interrupted
+                    record.updated_at = _now_iso()
+                to_persist.append(record)
+
+        # Bound the trailing status persistence within the remaining budget so a
+        # slow store (``_call_store_with_retry`` can back off under DB pressure)
+        # cannot push shutdown past ``timeout``.
+        if to_persist:
+            remaining = deadline - loop.time()
+            if remaining <= 0:
+                logger.warning("Run drain budget exhausted before persisting %d interrupted run(s) on shutdown", len(to_persist))
+            else:
+                try:
+                    results = await asyncio.wait_for(
+                        asyncio.gather(*(self._persist_status(record, RunStatus.interrupted) for record in to_persist), return_exceptions=True),
+                        timeout=remaining,
+                    )
+                except TimeoutError:
+                    logger.warning("Run drain status persistence exceeded the %.1fs budget; %d record(s) may not be persisted", timeout, len(to_persist))
+                else:
+                    # ``_persist_status`` is best-effort: it catches and logs its
+                    # own failures, returning ``False``. Inspect the aggregate so a
+                    # partial failure is surfaced at shutdown level (with the
+                    # run_id) instead of being silently swallowed by the gather.
+                    for record, result in zip(to_persist, results):
+                        if isinstance(result, Exception):
+                            logger.warning("Unexpected error persisting interrupted status for run %s during shutdown: %r", record.run_id, result)
+                        elif result is False:
+                            logger.warning("Could not persist interrupted status for run %s during shutdown", record.run_id)
+
+        if pending:
+            logger.warning("Run drain exceeded %.1fs on shutdown; %d run task(s) still active and may race checkpointer teardown", timeout, len(pending))
+        logger.info("Drained %d in-flight run(s) on shutdown (%d settled within %.1fs)", len(inflight), len(inflight) - len(pending), timeout)
+

 class ConflictError(Exception):
    """Raised when multitask_strategy=reject and thread has inflight runs."""
@@ -150,6 +150,7 @@ async def run_agent(
    pre_run_checkpoint_id: str | None = None
    pre_run_snapshot: dict[str, Any] | None = None
    snapshot_capture_failed = False
+    llm_error_fallback_message: str | None = None

    journal = None

@@ -312,6 +313,7 @@ async def run_agent(
                if record.abort_event.is_set():
                    logger.info("Run %s abort requested — stopping", run_id)
                    break
+                llm_error_fallback_message = llm_error_fallback_message or _extract_llm_error_fallback_message(chunk)
                sse_event = _lg_mode_to_sse_event(single_mode)
                await bridge.publish(run_id, sse_event, serialize(chunk, mode=single_mode))
        else:
@@ -330,6 +332,7 @@ async def run_agent(
                if mode is None:
                    continue

+                llm_error_fallback_message = llm_error_fallback_message or _extract_llm_error_fallback_message(chunk)
                sse_event = _lg_mode_to_sse_event(mode)
                await bridge.publish(run_id, sse_event, serialize(chunk, mode=mode))

@@ -352,6 +355,12 @@ async def run_agent(
                    logger.warning("Failed to rollback checkpoint for run %s", run_id, exc_info=True)
            else:
                await run_manager.set_status(run_id, RunStatus.interrupted)
+        elif llm_error_fallback_message or (journal is not None and journal.had_llm_error_fallback):
+            error_msg = llm_error_fallback_message
+            if error_msg is None and journal is not None:
+                error_msg = journal.llm_error_fallback_message
+            error_msg = error_msg or "LLM provider failed after retries"
+            await run_manager.set_status(run_id, RunStatus.error, error=error_msg)
        else:
            await run_manager.set_status(run_id, RunStatus.success)

@@ -554,6 +563,85 @@ def _lg_mode_to_sse_event(mode: str) -> str:
    return mode


+def _error_fallback_message_from_metadata(metadata: dict[str, Any], content: Any) -> str:
+    detail = metadata.get("error_detail")
+    if isinstance(detail, str) and detail.strip():
+        return detail.strip()
+    reason = metadata.get("error_reason")
+    if isinstance(reason, str) and reason.strip():
+        return reason.strip()
+    if isinstance(content, str) and content.strip():
+        return content.strip()[:2000]
+    return "LLM provider failed after retries"
+
+
+def _try_extract_from_message(obj: Any) -> str | None:
+    """Try to extract fallback marker from a single message object or dict."""
+    additional_kwargs = getattr(obj, "additional_kwargs", None)
+    if isinstance(additional_kwargs, dict) and additional_kwargs.get("deerflow_error_fallback"):
+        return _error_fallback_message_from_metadata(additional_kwargs, getattr(obj, "content", None))
+
+    if isinstance(obj, dict):
+        nested_kwargs = obj.get("additional_kwargs")
+        if isinstance(nested_kwargs, dict) and nested_kwargs.get("deerflow_error_fallback"):
+            return _error_fallback_message_from_metadata(nested_kwargs, obj.get("content"))
+    return None
+
+
+def _extract_llm_error_fallback_message(value: Any) -> str | None:
+    """Find LLM fallback markers in streamed LangGraph chunks.
+
+    Error fallback messages returned by model-call middleware are not guaranteed
+    to pass through LLM end callbacks, but they do appear in graph state chunks.
+    """
+    # Fast path: large state chunks produced by stream_mode="values" have a
+    # top-level "messages" list. Scanning only that list avoids expensive deep
+    # recursion into large state dicts.
+    if isinstance(value, dict):
+        messages = value.get("messages")
+        if isinstance(messages, (list, tuple)):
+            for msg in messages:
+                result = _try_extract_from_message(msg)
+                if result is not None:
+                    return result
+            # Fallback marker is attached to an AI message in the messages
+            # channel; it will never appear elsewhere in a values chunk.
+            return None
+        # No top-level "messages" — this is likely an "updates" chunk (small
+        # dict keyed by node name). Fall through to deep walk, which is cheap
+        # for these payloads.
+
+    # Deep walk for updates / messages / tuple / list modes. Payloads are
+    # small, so full recursion is acceptable here.
+    seen: set[int] = set()
+
+    def walk(obj: Any) -> str | None:
+        oid = id(obj)
+        if oid in seen:
+            return None
+        seen.add(oid)
+
+        result = _try_extract_from_message(obj)
+        if result is not None:
+            return result
+
+        if isinstance(obj, dict):
+            for item in obj.values():
+                result = walk(item)
+                if result is not None:
+                    return result
+            return None
+
+        if isinstance(obj, (list, tuple, set)):
+            for item in obj:
+                result = walk(item)
+                if result is not None:
+                    return result
+        return None
+
+    return walk(value)
+
+
 def _extract_human_message(graph_input: dict) -> HumanMessage | None:
    """Extract or construct a HumanMessage from graph_input for event recording.

@@ -1,4 +1,5 @@
 import asyncio
+import os
 import posixpath
 import re
 import shlex
@@ -43,6 +44,16 @@ _MAX_GLOB_MAX_RESULTS = 1000
 _DEFAULT_GREP_MAX_RESULTS = 100
 _MAX_GREP_MAX_RESULTS = 500
 _DEFAULT_WRITE_FILE_ERROR_MAX_CHARS = 2000
+
+# Maximum bytes accepted in a single non-append write_file call (issue #3189).
+# Oversized single-shot writes correlate with LLM streaming chunk-gap timeouts
+# because the tool-call JSON payload (which the model must emit as one
+# continuous stream) grows past the safe window. 80 KB ≈ 20K tokens, a
+# comfortable headroom under the factory-default 240s stream_chunk_timeout.
+# Deployments can override via env var DEERFLOW_WRITE_FILE_MAX_BYTES; set to
+# 0 (or negative) to disable the guard entirely.
+_WRITE_FILE_CONTENT_MAX_BYTES = 80 * 1024
+_WRITE_FILE_MAX_BYTES_ENV = "DEERFLOW_WRITE_FILE_MAX_BYTES"
 _LOCAL_BASH_CWD_COMMANDS = {"cd", "pushd"}
 _LOCAL_BASH_COMMAND_WRAPPERS = {"command", "builtin"}
 _LOCAL_BASH_COMMAND_PREFIX_KEYWORDS = {"!", "{", "case", "do", "elif", "else", "for", "if", "select", "then", "time", "until", "while"}
@@ -1671,6 +1682,23 @@ async def _read_file_tool_async(
 read_file_tool.coroutine = _read_file_tool_async


+def _effective_write_file_max_bytes() -> int:
+    """Return the active size cap for non-append write_file calls.
+
+    Reads ``DEERFLOW_WRITE_FILE_MAX_BYTES`` at call time (not import time)
+    so tests and runtime tweaks take effect without restart. Falls back to
+    the default on missing/malformed values. A non-positive value disables
+    the guard.
+    """
+    raw = os.environ.get(_WRITE_FILE_MAX_BYTES_ENV)
+    if raw is None:
+        return _WRITE_FILE_CONTENT_MAX_BYTES
+    try:
+        return int(raw)
+    except ValueError:
+        return _WRITE_FILE_CONTENT_MAX_BYTES
+
+
@tool("write_file", parse_docstring=True)
 def write_file_tool(
    runtime: Runtime,
@@ -1679,14 +1707,47 @@ def write_file_tool(
    content: str,
    append: bool = False,
 ) -> str:
-    """Write text content to a file. By default this overwrites the target file; set append to true to add content to the end without replacing existing content.
+    """Write text content to a file. By default this overwrites the target file; set append=True to add content to the end without replacing existing content.
+
+    SIZE POLICY (issue #3189):
+    A single non-append write_file call must not exceed 80 KB of UTF-8 content.
+    Oversized single-shot writes correlate with LLM streaming chunk-gap
+    timeouts because the tool-call JSON payload — which the model must emit as
+    one continuous stream — grows past the safe window. For larger documents,
+    use ONE of these strategies (write_file rejects oversized payloads with an
+    actionable error):
+
+      1. INCREMENTAL EDIT (preferred for revisions): after the initial write,
+         use `str_replace` to surgically update sections. This is the same
+         pattern Claude Code's Write+Edit and OpenAI Codex's apply_patch use,
+         and keeps each tool call's payload small.
+      2. APPEND-IN-CHUNKS (for new long-form content): split the document into
+         sections, each well under 80 KB. First call uses append=False to
+         create the file; subsequent calls use append=True. The 80 KB cap does
+         NOT apply to append=True calls.
+
+    Operators can override the cap via env var `DEERFLOW_WRITE_FILE_MAX_BYTES`
+    (0 disables the guard entirely). Raising it risks streaming timeouts.

    Args:
        description: Explain why you are writing to this file in short words. ALWAYS PROVIDE THIS PARAMETER FIRST.
        path: The **absolute** path to the file to write to. ALWAYS PROVIDE THIS PARAMETER SECOND.
        content: The content to write to the file. ALWAYS PROVIDE THIS PARAMETER THIRD.
-        append: Whether to append content to the end of the file instead of overwriting it. Defaults to false.
+        append: Whether to append content to the end of the file instead of overwriting it. Defaults to False.
    """
+    if not append:
+        max_bytes = _effective_write_file_max_bytes()
+        if max_bytes > 0:
+            content_bytes = len(content.encode("utf-8"))
+            if content_bytes > max_bytes:
+                return (
+                    f"Error: write_file content ({content_bytes} bytes) exceeds the "
+                    f"{max_bytes}-byte single-call limit. Split the content into smaller "
+                    "pieces: either (a) write the first section now, then use `str_replace` "
+                    "for further edits, or (b) call write_file again with append=True "
+                    "carrying the next section. See SIZE POLICY in the tool docstring "
+                    "or issue #3189 for the rationale."
+                )
    try:
        requested_path = path
        sandbox = ensure_sandbox_initialized(runtime)
@@ -13,6 +13,7 @@ import stat
 import zipfile
 from pathlib import Path, PurePosixPath, PureWindowsPath

+from deerflow.skills.permissions import make_skill_tree_sandbox_readable
 from deerflow.skills.security_scanner import scan_skill_content

 logger = logging.getLogger(__name__)
@@ -139,6 +140,7 @@ def _move_staged_skill_into_reserved_target(staging_target: Path, target: Path)
        reserved = True
        for child in staging_target.iterdir():
            shutil.move(str(child), target / child.name)
+        make_skill_tree_sandbox_readable(target)
        installed = True
    except FileExistsError as e:
        raise SkillAlreadyExistsError(f"Skill '{target.name}' already exists") from e
@@ -9,6 +9,37 @@ from .types import SKILL_MD_FILE, Skill, SkillCategory
 logger = logging.getLogger(__name__)


+def _format_yaml_error(skill_file: Path, exc: yaml.YAMLError, source: str) -> str:
+    """Render a developer-friendly explanation of a YAML front-matter error."""
+
+    lines = [f"Invalid YAML front-matter in {skill_file}: {exc}"]
+
+    mark = getattr(exc, "problem_mark", None)
+    source_lines = source.splitlines()
+    if mark is not None and 0 <= mark.line < len(source_lines):
+        offending = source_lines[mark.line]
+
+        # mark.line is 0-based within the front-matter body; +1 makes it
+        # 1-based, +1 more accounts for the leading `---` fence that the
+        # front-matter regex strips before yaml.safe_load sees it. The
+        # result matches the line number an author sees in their editor.
+        file_line_number = mark.line + 2
+        lines.append(f"  line {file_line_number}: {offending}")
+
+        # Targeted hint for the most common authoring mistake: an unquoted
+        # scalar value whose body contains ``: ``. We only surface the hint
+        # when we are confident it applies, to avoid misleading authors who
+        # hit unrelated YAML errors.
+        if getattr(exc, "problem", "") == "mapping values are not allowed here" and ":" in offending:
+            key, _, value = offending.partition(":")
+            value = value.strip()
+            if value and value[0] not in {'"', "'", "|", ">", "[", "{"}:
+                escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+                lines.append(f'  hint: values containing ":" must be quoted, e.g. {key}: "{escaped}"')
+
+    return "\n".join(lines)
+
+
 def parse_allowed_tools(raw: object, skill_file: Path) -> list[str] | None:
    """Parse the optional allowed-tools frontmatter field.

@@ -60,7 +91,7 @@ def parse_skill_file(skill_file: Path, category: SkillCategory, relative_path: P
        try:
            metadata = yaml.safe_load(front_matter_text)
        except yaml.YAMLError as exc:
-            logger.error("Invalid YAML front-matter in %s: %s", skill_file, exc)
+            logger.error("%s", _format_yaml_error(skill_file, exc, front_matter_text))
            return None

        if not isinstance(metadata, dict):
@@ -0,0 +1,34 @@
+"""Filesystem permission helpers for installed skill trees."""
+
+import stat
+from pathlib import Path
+
+
+def make_skill_path_sandbox_readable(path: Path) -> None:
+    if path.is_symlink():
+        return
+    mode = stat.S_IMODE(path.stat().st_mode)
+    without_sandbox_write = mode & ~(stat.S_IWGRP | stat.S_IWOTH)
+    if path.is_dir():
+        path.chmod(without_sandbox_write | 0o555)
+    elif path.is_file():
+        path.chmod(without_sandbox_write | 0o444)
+
+
+def make_skill_tree_sandbox_readable(target: Path) -> None:
+    make_skill_path_sandbox_readable(target)
+    for path in target.rglob("*"):
+        make_skill_path_sandbox_readable(path)
+
+
+def make_skill_written_path_sandbox_readable(skill_root: Path, target: Path) -> None:
+    resolved_root = skill_root.resolve()
+    resolved_target = target.resolve()
+    resolved_target.relative_to(resolved_root)
+
+    make_skill_path_sandbox_readable(resolved_root)
+    current = resolved_root
+    for part in resolved_target.parent.relative_to(resolved_root).parts:
+        current = current / part
+        make_skill_path_sandbox_readable(current)
+    make_skill_path_sandbox_readable(resolved_target)
@@ -13,6 +13,7 @@ from datetime import UTC, datetime
 from pathlib import Path

 from deerflow.config.runtime_paths import resolve_path
+from deerflow.skills.permissions import make_skill_written_path_sandbox_readable
 from deerflow.skills.storage.skill_storage import SKILL_MD_FILE, SkillStorage
 from deerflow.skills.types import SkillCategory

@@ -90,6 +91,7 @@ class LocalSkillStorage(SkillStorage):
            tmp_file.write(content)
            tmp_path = Path(tmp_file.name)
        tmp_path.replace(target)
+        make_skill_written_path_sandbox_readable(self.get_custom_skill_dir(name), target)

    async def ainstall_skill_from_archive(self, archive_path: str | Path) -> dict:
        import zipfile
@@ -24,6 +24,17 @@ Do NOT use for simple, single-step operations.""",
 - Do NOT ask for clarification - work with the information provided
 </guidelines>

+<file_editing_workflow>
+When revising an existing file, prefer `str_replace` over `write_file` —
+it sends only the diff and avoids re-emitting the whole file (mirrors
+Claude Code's Edit and Codex's apply_patch). When writing long new
+content from scratch, split it into sections: the first `write_file`
+call creates the file, then use `write_file` with append=True to extend
+it section by section. This keeps each tool call small and avoids
+mid-stream chunk-gap timeouts on oversized single-shot writes.
+(See issue #3189.)
+</file_editing_workflow>
+
 <output_format>
 When you complete the task, provide:
 1. A brief summary of what was accomplished
@@ -1,202 +1,181 @@
 """Tool search — deferred tool discovery at runtime.

 Contains:
- DeferredToolRegistry: stores deferred tools and handles regex search
- tool_search: the LangChain tool the agent calls to discover deferred tools
+- DeferredToolCatalog: immutable, searchable catalog of deferred tools.
+- build_tool_search_tool: builds the `tool_search` tool as a closure over a
+  catalog; it records promotions into graph state via ``Command``.
+- build_deferred_tool_setup: assembles the catalog + tool from a
+  policy-filtered tool list (call AFTER tool-policy filtering).

 The agent sees deferred tool names in <available-deferred-tools> but cannot
-call them until it fetches their full schema via the tool_search tool.
-Source-agnostic: no mention of MCP or tool origin.
+call them until it fetches their full schema via the tool_search tool. The
+deferred set rides on a build-time closure and promotion lives in per-thread
+graph state — there is no ContextVar. Source-agnostic: a tool is "deferred"
+when it carries the ``deerflow_mcp`` metadata tag.
 """

-import contextvars
+import hashlib
 import json
 import logging
 import re
 from dataclasses import dataclass
+from functools import cached_property
+from typing import Annotated

 from langchain.tools import BaseTool
-from langchain_core.tools import tool
+from langchain_core.messages import ToolMessage
+from langchain_core.tools import InjectedToolCallId, tool
 from langchain_core.utils.function_calling import convert_to_openai_function
+from langgraph.types import Command
+
+from deerflow.tools.mcp_metadata import is_mcp_tool

 logger = logging.getLogger(__name__)

 MAX_RESULTS = 5  # Max tools returned per search


-# ── Registry ──
+def _compile_catalog_regex(pattern: str) -> re.Pattern[str]:
+    """Compile ``pattern`` case-insensitively, falling back to a literal match.
+
+    Search queries come from the model, so an invalid regex (e.g. an unbalanced
+    paren) must degrade to a literal substring match rather than raise.
+    """
+    try:
+        return re.compile(pattern, re.IGNORECASE)
+    except re.error:
+        return re.compile(re.escape(pattern), re.IGNORECASE)


-@dataclass
-class DeferredToolEntry:
-    """Lightweight metadata for a deferred tool (no full schema in context)."""
-
-    name: str
-    description: str
-    tool: BaseTool  # Full tool object, returned only on search match
+# ── Catalog ──


-class DeferredToolRegistry:
-    """Registry of deferred tools, searchable by regex pattern."""
+# NOTE: frozen=True without slots=True keeps __dict__, which is what lets the
+# @cached_property fields below cache (they write to instance.__dict__, bypassing
+# the frozen __setattr__). Do NOT add slots=True or hash/names break at runtime.
+@dataclass(frozen=True)
+class DeferredToolCatalog:
+    """Immutable catalog of deferred tools. Pure search, no mutation."""

-    def __init__(self):
-        self._entries: list[DeferredToolEntry] = []
+    tools: tuple[BaseTool, ...]

-    def register(self, tool: BaseTool) -> None:
-        self._entries.append(
-            DeferredToolEntry(
-                name=tool.name,
-                description=tool.description or "",
-                tool=tool,
-            )
-        )
+    @cached_property
+    def names(self) -> frozenset[str]:
+        return frozenset(t.name for t in self.tools)

-    def promote(self, names: set[str]) -> None:
-        """Remove tools from the deferred registry so they pass through the filter.
-
-        Called after tool_search returns a tool's schema — the LLM now knows
-        the full definition, so the DeferredToolFilterMiddleware should stop
-        stripping it from bind_tools on subsequent calls.
-        """
-        if not names:
-            return
-        before = len(self._entries)
-        self._entries = [e for e in self._entries if e.name not in names]
-        promoted = before - len(self._entries)
-        if promoted:
-            logger.debug(f"Promoted {promoted} tool(s) from deferred to active: {names}")
+    @cached_property
+    def hash(self) -> str:
+        canon = [{"name": t.name, "schema": convert_to_openai_function(t)} for t in sorted(self.tools, key=lambda t: t.name)]
+        blob = json.dumps(canon, sort_keys=True, ensure_ascii=False, default=str)
+        return hashlib.sha256(blob.encode("utf-8")).hexdigest()[:16]

    def search(self, query: str) -> list[BaseTool]:
-        """Search deferred tools by regex pattern against name + description.
+        query = query.strip()
+        if not query:
+            return []

-        Supports three query forms (aligned with Claude Code):
-          - "select:name1,name2" — exact name match
-          - "+keyword rest" — name must contain keyword, rank by rest
-          - "keyword query" — regex match against name + description
-
-        Returns:
-            List of matched BaseTool objects (up to MAX_RESULTS).
-        """
        if query.startswith("select:"):
-            names = {n.strip() for n in query[7:].split(",")}
-            return [e.tool for e in self._entries if e.name in names][:MAX_RESULTS]
+            wanted = {n.strip() for n in query[7:].split(",")}
+            return [t for t in self.tools if t.name in wanted][:MAX_RESULTS]

        if query.startswith("+"):
            parts = query[1:].split(None, 1)
+            if not parts:
+                return []  # bare "+" with no required token — nothing to require
            required = parts[0].lower()
-            candidates = [e for e in self._entries if required in e.name.lower()]
+            candidates = [t for t in self.tools if required in t.name.lower()]
            if len(parts) > 1:
-                candidates.sort(
-                    key=lambda e: _regex_score(parts[1], e),
-                    reverse=True,
-                )
-            return [e.tool for e in candidates][:MAX_RESULTS]
+                candidates.sort(key=lambda t: _catalog_regex_score(parts[1], t), reverse=True)
+            return candidates[:MAX_RESULTS]

-        # General regex search
-        try:
-            regex = re.compile(query, re.IGNORECASE)
-        except re.error:
-            regex = re.compile(re.escape(query), re.IGNORECASE)
-
-        scored = []
-        for entry in self._entries:
-            searchable = f"{entry.name} {entry.description}"
+        regex = _compile_catalog_regex(query)
+        scored: list[tuple[int, BaseTool]] = []
+        for t in self.tools:
+            searchable = f"{t.name} {t.description or ''}"
            if regex.search(searchable):
-                score = 2 if regex.search(entry.name) else 1
-                scored.append((score, entry))
-
+                scored.append((2 if regex.search(t.name) else 1, t))
        scored.sort(key=lambda x: x[0], reverse=True)
-        return [entry.tool for _, entry in scored][:MAX_RESULTS]
-
-    @property
-    def entries(self) -> list[DeferredToolEntry]:
-        return list(self._entries)
-
-    @property
-    def deferred_names(self) -> set[str]:
-        """Names of tools that are still hidden from model binding."""
-        return {entry.name for entry in self._entries}
-
-    def contains(self, name: str) -> bool:
-        """Return whether *name* is still deferred."""
-        return any(entry.name == name for entry in self._entries)
-
-    def __len__(self) -> int:
-        return len(self._entries)
+        return [t for _, t in scored][:MAX_RESULTS]


-def _regex_score(pattern: str, entry: DeferredToolEntry) -> int:
-    try:
-        regex = re.compile(pattern, re.IGNORECASE)
-    except re.error:
-        regex = re.compile(re.escape(pattern), re.IGNORECASE)
-    return len(regex.findall(f"{entry.name} {entry.description}"))
+def _catalog_regex_score(pattern: str, t: BaseTool) -> int:
+    regex = _compile_catalog_regex(pattern)
+    return len(regex.findall(f"{t.name} {t.description or ''}"))


-# ── Per-request registry (ContextVar) ──
-#
-# Using a ContextVar instead of a module-level global prevents concurrent
-# requests from clobbering each other's registry.  In asyncio-based LangGraph
-# each graph run executes in its own async context, so each request gets an
-# independent registry value.  For synchronous tools run via
-# loop.run_in_executor, Python copies the current context to the worker thread,
-# so the ContextVar value is correctly inherited there too.
-
-_registry_var: contextvars.ContextVar[DeferredToolRegistry | None] = contextvars.ContextVar("deferred_tool_registry", default=None)
+# ── Setup / tool ──


-def get_deferred_registry() -> DeferredToolRegistry | None:
-    return _registry_var.get()
+@dataclass(frozen=True)
+class DeferredToolSetup:
+    """Result of assembling deferred-tool support for one agent build.

+    The three fields move as a unit, so callers branch on ``tool_search_tool``:

-def set_deferred_registry(registry: DeferredToolRegistry) -> None:
-    _registry_var.set(registry)
+    - **Empty** ``(None, frozenset(), None)``: deferral is disabled, or no MCP
+      tool survived policy filtering. Nothing is deferred — bind tools as-is.
+    - **Populated**: ``tool_search_tool`` is appended to the agent's tools,
+      ``deferred_names`` are withheld from the model until promoted, and
+      ``catalog_hash`` scopes those promotions in graph state.

-
-def reset_deferred_registry() -> None:
-    """Reset the deferred registry for the current async context."""
-    _registry_var.set(None)
-
-
-# ── Tool ──
-
-
-@tool
-def tool_search(query: str) -> str:
-    """Fetches full schema definitions for deferred tools so they can be called.
-
-    Deferred tools appear by name in <available-deferred-tools> in the system
-    prompt. Until fetched, only the name is known — there is no parameter
-    schema, so the tool cannot be invoked. This tool takes a query, matches
-    it against the deferred tool list, and returns the matched tools' complete
-    definitions. Once a tool's schema appears in that result, it is callable.
-
-    Query forms:
-      - "select:Read,Edit,Grep" — fetch these exact tools by name
-      - "notebook jupyter" — keyword search, up to max_results best matches
-      - "+slack send" — require "slack" in the name, rank by remaining terms
-
-    Args:
-        query: Query to find deferred tools. Use "select:<tool_name>" for
-               direct selection, or keywords to search.
-
-    Returns:
-        Matched tool definitions as JSON array.
+    Invariant: ``tool_search_tool is None`` ⟺ ``deferred_names`` is empty ⟺
+    ``catalog_hash is None``.
    """
-    registry = get_deferred_registry()
-    if not registry:
-        return "No deferred tools available."

-    matched_tools = registry.search(query)
-    if not matched_tools:
-        return f"No tools found matching: {query}"
+    tool_search_tool: BaseTool | None
+    deferred_names: frozenset[str]
+    catalog_hash: str | None

-    # Use LangChain's built-in serialization to produce OpenAI function format.
-    # This is model-agnostic: all LLMs understand this standard schema.
-    tool_defs = [convert_to_openai_function(t) for t in matched_tools[:MAX_RESULTS]]

-    # Promote matched tools so the DeferredToolFilterMiddleware stops filtering
-    # them from bind_tools — the LLM now has the full schema and can invoke them.
-    registry.promote({t.name for t in matched_tools[:MAX_RESULTS]})
+def build_tool_search_tool(catalog: DeferredToolCatalog) -> BaseTool:
+    catalog_hash = catalog.hash

-    return json.dumps(tool_defs, indent=2, ensure_ascii=False)
+    @tool
+    def tool_search(query: str, tool_call_id: Annotated[str, InjectedToolCallId]) -> Command:
+        """Fetches full schema definitions for deferred tools so they can be called.
+
+        Deferred tools appear by name in <available-deferred-tools> in the system
+        prompt. Until fetched, only the name is known. This tool matches a query
+        against the deferred tools and returns the matched tools complete schemas;
+        once returned, a tool becomes callable.
+
+        Query forms:
+          - "select:Read,Edit" -- fetch these exact tools by name
+          - "notebook jupyter" -- keyword search, up to max_results best matches
+          - "+slack send" -- require "slack" in the name, rank by remaining terms
+        """
+        matched = catalog.search(query)[:MAX_RESULTS]
+        if not matched:
+            content, names = f"No tools found matching: {query}", []
+        else:
+            content = json.dumps([convert_to_openai_function(t) for t in matched], indent=2, ensure_ascii=False)
+            names = [t.name for t in matched]
+        return Command(
+            update={
+                "promoted": {"catalog_hash": catalog_hash, "names": names},
+                "messages": [ToolMessage(content=content, tool_call_id=tool_call_id, name="tool_search")],
+            }
+        )
+
+    return tool_search
+
+
+def build_deferred_tool_setup(filtered_tools: list[BaseTool], *, enabled: bool) -> DeferredToolSetup:
+    """Build the deferred-tool setup from a POLICY-FILTERED tool list.
+
+    Must be called after skill/agent tool-policy filtering so the catalog never
+    exposes a tool the current agent is not allowed to use.
+
+    Returns an empty setup (see :class:`DeferredToolSetup`) in two distinct
+    cases: deferral is disabled, or it is enabled but no MCP tool survived
+    filtering.
+    """
+    if not enabled:
+        # Deferral disabled: defer nothing; the model binds every tool as before.
+        return DeferredToolSetup(None, frozenset(), None)
+    deferred = [t for t in filtered_tools if is_mcp_tool(t)]
+    if not deferred:
+        # Enabled, but no MCP tool to defer: same empty result, different reason.
+        return DeferredToolSetup(None, frozenset(), None)
+    catalog = DeferredToolCatalog(tuple(deferred))
+    return DeferredToolSetup(build_tool_search_tool(catalog), catalog.names, catalog.hash)
@@ -17,12 +17,13 @@ from __future__ import annotations
 import logging
 import tempfile
 from pathlib import Path
-from typing import Any
+from typing import Annotated, Any

 import yaml
 from langchain_core.messages import ToolMessage
 from langchain_core.tools import tool
 from langgraph.types import Command
+from pydantic import BeforeValidator

 from deerflow.config.agents_config import load_agent_config, validate_agent_name
 from deerflow.config.app_config import get_app_config
@@ -32,6 +33,8 @@ from deerflow.tools.types import Runtime

 logger = logging.getLogger(__name__)

+_NULLISH_STRINGS = frozenset({"null", "none", "undefined"})
+

 def _stage_temp(path: Path, text: str) -> Path:
    """Write ``text`` into a sibling temp file and return its path.
@@ -67,14 +70,26 @@ def _cleanup_temps(temps: list[Path]) -> None:
            logger.debug("Failed to clean up temp file %s", tmp, exc_info=True)


+def _is_nullish_string(value: object) -> bool:
+    return isinstance(value, str) and value.strip().lower() in _NULLISH_STRINGS
+
+
+def _normalize_nullish_string(value: object) -> object:
+    return None if _is_nullish_string(value) else value
+
+
+OptionalText = Annotated[str | None, BeforeValidator(_normalize_nullish_string)]
+OptionalStringList = Annotated[list[str] | None, BeforeValidator(_normalize_nullish_string)]
+
+
@tool(parse_docstring=True)
 def update_agent(
    runtime: Runtime,
-    soul: str | None = None,
-    description: str | None = None,
-    skills: list[str] | None = None,
-    tool_groups: list[str] | None = None,
-    model: str | None = None,
+    soul: OptionalText = None,
+    description: OptionalText = None,
+    skills: OptionalStringList = None,
+    tool_groups: OptionalStringList = None,
+    model: OptionalText = None,
 ) -> Command:
    """Persist updates to the current custom agent's SOUL.md and config.yaml.

@@ -86,7 +101,9 @@ def update_agent(
    semantics, so always start from the current SOUL and apply your edits.

    Pass ``skills=[]`` to disable all skills for this agent. Omit ``skills``
-    entirely to keep the existing whitelist.
+    entirely to keep the existing whitelist. Do not pass literal strings like
+    ``"null"`` / ``"none"`` / ``"undefined"`` for unchanged fields; omit those
+    fields instead.

    Args:
        soul: Optional full replacement SOUL.md content.
@@ -104,10 +121,10 @@ def update_agent(
    agent_name_raw: str | None = runtime.context.get("agent_name") if runtime.context else None

    def _err(message: str) -> Command:
-        return Command(update={"messages": [ToolMessage(content=f"Error: {message}", tool_call_id=tool_call_id)]})
+        return Command(update={"messages": [ToolMessage(content=f"Error: {message}", tool_call_id=tool_call_id, status="error")]})

    if soul is None and description is None and skills is None and tool_groups is None and model is None:
-        return _err("No fields provided. Pass at least one of: soul, description, skills, tool_groups, model.")
+        return _err('No fields provided. Pass at least one of: soul, description, skills, tool_groups, model. Omit unchanged fields instead of passing null-like strings such as "null", "none", or "undefined".')

    try:
        agent_name = validate_agent_name(agent_name_raw)
@@ -0,0 +1,29 @@
+"""Single source of truth for the MCP-tool metadata tag.
+
+A tool is "MCP-sourced" when it carries the ``deerflow_mcp`` metadata flag.
+The tag is *written* where MCP tools are loaded (``tools.py``) and *read* by
+deferred-tool assembly (``tool_search.py``) and the agent build site
+(``agent.py``). Keeping the key, the tagger, and the predicate here means the
+magic string lives in exactly one place, and readers import a public predicate
+instead of a private cross-module helper.
+
+This is a leaf module by design: it depends only on ``BaseTool`` so that any
+module (including the tool loader) can import it without an import cycle.
+"""
+
+from __future__ import annotations
+
+from langchain.tools import BaseTool
+
+MCP_TOOL_METADATA_KEY = "deerflow_mcp"
+
+
+def tag_mcp_tool(tool: BaseTool) -> BaseTool:
+    """Mark ``tool`` as MCP-sourced. Mutates in place and returns it for chaining."""
+    tool.metadata = {**(tool.metadata or {}), MCP_TOOL_METADATA_KEY: True}
+    return tool
+
+
+def is_mcp_tool(tool: BaseTool) -> bool:
+    """True when ``tool`` carries the MCP-source tag written by :func:`tag_mcp_tool`."""
+    return (getattr(tool, "metadata", None) or {}).get(MCP_TOOL_METADATA_KEY) is True
@@ -7,7 +7,7 @@ from deerflow.config.app_config import AppConfig
 from deerflow.reflection import resolve_variable
 from deerflow.sandbox.security import is_host_bash_allowed
 from deerflow.tools.builtins import ask_clarification_tool, present_file_tool, task_tool, view_image_tool
-from deerflow.tools.builtins.tool_search import get_deferred_registry
+from deerflow.tools.mcp_metadata import tag_mcp_tool
 from deerflow.tools.sync import make_sync_tool_wrapper

 logger = logging.getLogger(__name__)
@@ -127,57 +127,13 @@ def get_available_tools(
                if mcp_tools:
                    logger.info(f"Using {len(mcp_tools)} cached MCP tool(s)")

-                    # When tool_search is enabled, register MCP tools in the
-                    # deferred registry and add tool_search to builtin tools.
-                    if config.tool_search.enabled:
-                        from deerflow.tools.builtins.tool_search import DeferredToolRegistry, set_deferred_registry
-                        from deerflow.tools.builtins.tool_search import tool_search as tool_search_tool
-
-                        # Reuse the existing registry if one is already set for
-                        # this async context. ``get_available_tools`` is
-                        # re-entered whenever a subagent is spawned
-                        # (``task_tool`` calls it to build the child agent's
-                        # toolset), and previously we used to unconditionally
-                        # rebuild the registry — wiping out the parent agent's
-                        # tool_search promotions. The
-                        # ``DeferredToolFilterMiddleware`` then re-hid those
-                        # tools from subsequent model calls, leaving the agent
-                        # able to see a tool's name but unable to invoke it
-                        # (issue #2884). ``contextvars`` already gives us the
-                        # lifetime semantics we want: a fresh request / graph
-                        # run starts in a new asyncio task with the
-                        # ContextVar at its default of ``None``, so reuse is
-                        # only triggered for re-entrant calls inside one run.
-                        #
-                        # Intentionally NOT reconciling against the current
-                        # ``mcp_tools`` snapshot. The MCP cache only refreshes
-                        # on ``extensions_config.json`` mtime changes, which
-                        # in practice happens between graph runs — not inside
-                        # one. And even if a refresh did happen mid-run, the
-                        # already-built lead agent's ``ToolNode`` still holds
-                        # the *previous* tool set (LangGraph binds tools at
-                        # graph construction time), so a brand-new MCP tool
-                        # couldn't actually be invoked anyway. The
-                        # ``DeferredToolRegistry`` doesn't retain the names
-                        # of previously-promoted tools (``promote()`` drops
-                        # the entry entirely), so re-syncing the registry
-                        # against a fresh ``mcp_tools`` list would
-                        # mis-classify those promotions as new tools and
-                        # re-register them as deferred — exactly the bug
-                        # this fix exists to prevent.
-                        existing_registry = get_deferred_registry()
-                        if existing_registry is None:
-                            registry = DeferredToolRegistry()
-                            for t in mcp_tools:
-                                registry.register(t)
-                            set_deferred_registry(registry)
-                            logger.info(f"Tool search active: {len(mcp_tools)} tools deferred")
-                        else:
-                            mcp_tool_names = {t.name for t in mcp_tools}
-                            still_deferred = len(existing_registry)
-                            promoted_count = max(0, len(mcp_tool_names) - still_deferred)
-                            logger.info(f"Tool search active (preserved promotions): {still_deferred} tools deferred, {promoted_count} already promoted")
-                        builtin_tools.append(tool_search_tool)
+                    # Tag MCP-sourced tools so deferred-tool assembly (done at
+                    # the agent construction site, AFTER tool-policy filtering)
+                    # can identify them. No ContextVar / registry is built here;
+                    # the deferred catalog + tool_search tool are assembled per
+                    # agent from the policy-filtered tool list.
+                    for t in mcp_tools:
+                        tag_mcp_tool(t)
        except ImportError:
            logger.warning("MCP module not available. Install 'langchain-mcp-adapters' package to enable MCP tools.")
        except Exception as e:
@@ -226,8 +226,7 @@ def list_files_in_dir(directory: Path) -> dict:
    Returns:
        Dict with "files" list (sorted by name) and "count".
        Each file entry has ``size`` as *int* (bytes).  Call
-        :func:`enrich_file_listing` to stringify sizes and add
-        virtual / artifact URLs.
+        :func:`enrich_file_listing` to add virtual / artifact URLs.
    """
    if not directory.is_dir():
        return {"files": [], "count": 0}
@@ -298,13 +297,12 @@ def upload_virtual_path(filename: str) -> str:


 def enrich_file_listing(result: dict, thread_id: str) -> dict:
-    """Add virtual paths, artifact URLs, and stringify sizes on a listing result.
+    """Add virtual paths and artifact URLs on a listing result.

    Mutates *result* in place and returns it for convenience.
    """
    for f in result["files"]:
        filename = f["filename"]
-        f["size"] = str(f["size"])
        f["virtual_path"] = upload_virtual_path(filename)
        f["artifact_url"] = upload_artifact_url(thread_id, filename)
    return result
@@ -0,0 +1,16 @@
+from fastapi.testclient import TestClient
+
+
+def assert_run_message_page(
+    client: TestClient,
+    url: str,
+    *,
+    expected_seq: list[int],
+    has_more: bool = True,
+) -> None:
+    response = client.get(url)
+
+    assert response.status_code == 200
+    body = response.json()
+    assert body["has_more"] is has_more
+    assert [m["seq"] for m in body["data"]] == expected_seq
@@ -0,0 +1,62 @@
+"""Regression anchor: JsonlRunEventStore async API must not block the loop.
+
+``JsonlRunEventStore`` is the ``run_events.backend == "jsonl"`` implementation.
+Its ``async def`` methods perform synchronous filesystem IO (``Path.glob``,
+``read_text``, ``open``, ``unlink``) that must be offloaded with
+``asyncio.to_thread`` (fixed in #3084). ``put`` runs on every emitted run event,
+so any blocking IO here stalls the event loop on the hot path.
+
+#3084 added a mock-based offload assertion in
+``tests/test_jsonl_event_store_async_io.py`` that covers ``put`` only. This
+anchor complements it by driving the **full** async surface (``put``,
+``put_batch``, ``list_messages``, ``list_events``, ``list_messages_by_run``,
+``count_messages``, ``delete_by_run``, ``delete_by_thread``) under the strict
+Blockbuster runtime gate, so any blocking IO reintroduced on the event loop in
+any of these methods — not just removal of a specific ``to_thread`` call —
+fails CI.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+pytestmark = pytest.mark.asyncio
+
+
+async def test_jsonl_run_event_store_async_api_does_not_block_event_loop(tmp_path: Path) -> None:
+    from deerflow.runtime.events.store.jsonl import JsonlRunEventStore
+
+    store = JsonlRunEventStore(base_dir=str(tmp_path))
+
+    # Seed an existing run file so put()'s seq-load globs + reads, and the
+    # read/delete paths have files to scan. Test-side IO is invisible to the
+    # gate (this module is not in scanned_modules).
+    thread_dir = tmp_path / "threads" / "t1" / "runs"
+    thread_dir.mkdir(parents=True, exist_ok=True)
+    (thread_dir / "r0.jsonl").write_text('{"seq": 1, "category": "message", "run_id": "r0"}\n', encoding="utf-8")
+
+    # writes: put + put_batch
+    record = await store.put(thread_id="t1", run_id="r1", event_type="message", category="message", content="hi")
+    assert record["seq"] >= 2
+    batch = await store.put_batch(
+        [
+            {"thread_id": "t1", "run_id": "r2", "event_type": "message", "category": "message", "content": "a"},
+            {"thread_id": "t1", "run_id": "r2", "event_type": "trace", "category": "trace", "content": "b"},
+        ]
+    )
+    assert len(batch) == 2
+
+    # reads: list_messages / list_events / list_messages_by_run / count_messages.
+    # list_events is exercised both without and with the event_types filter so
+    # the filter branch runs after _read_run_events' filesystem IO.
+    assert isinstance(await store.list_messages("t1"), list)
+    assert isinstance(await store.list_events("t1", "r1"), list)
+    assert isinstance(await store.list_events("t1", "r1", event_types=["message"]), list)
+    assert isinstance(await store.list_messages_by_run("t1", "r2"), list)
+    assert await store.count_messages("t1") >= 1
+
+    # deletes: delete_by_run (single file) then delete_by_thread (remaining)
+    assert await store.delete_by_run("t1", "r2") >= 1
+    assert await store.delete_by_thread("t1") >= 1
@@ -0,0 +1,56 @@
+"""Regression anchor: UploadsMiddleware must not block the event loop.
+
+``before_agent`` scans the thread uploads directory (``exists`` / ``iterdir`` /
+``stat`` plus reading sibling ``.md`` outlines). LangChain wires a sync-only
+``before_agent`` as ``RunnableCallable(before_agent, None)``; langgraph's
+``ainvoke`` runs it directly on the event loop when ``afunc is None``. So the
+filesystem scan must be offloaded (the middleware provides ``abefore_agent``).
+
+This anchor drives the real ``create_agent`` graph via ``ainvoke`` under the
+strict Blockbuster gate. If the scan regresses back onto the event loop,
+Blockbuster raises ``BlockingError`` and this test fails.
+
+The graph/middleware construction is offloaded with ``asyncio.to_thread`` only
+because ``Paths.__init__`` resolves paths synchronously; the surface under test
+(``before_agent``'s directory scan) is exercised on the event loop, not
+bypassed.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+import pytest
+from langchain_core.language_models.fake_chat_models import FakeMessagesListChatModel
+from langchain_core.messages import AIMessage, HumanMessage
+
+pytestmark = pytest.mark.asyncio
+
+
+class _FakeModel(FakeMessagesListChatModel):
+    """FakeMessagesListChatModel with a no-op ``bind_tools`` for create_agent."""
+
+    def bind_tools(self, tools, **kwargs):  # type: ignore[override]
+        return self
+
+
+async def test_before_agent_uploads_scan_does_not_block_event_loop(tmp_path: Path) -> None:
+    from langchain.agents import create_agent
+
+    from deerflow.agents.middlewares.uploads_middleware import UploadsMiddleware
+    from deerflow.runtime.user_context import get_effective_user_id
+
+    mw = await asyncio.to_thread(UploadsMiddleware, str(tmp_path))
+    uploads_dir = await asyncio.to_thread(mw._paths.sandbox_uploads_dir, "t1", user_id=get_effective_user_id())
+    uploads_dir.mkdir(parents=True, exist_ok=True)  # test-side seeding (not in scanned_modules)
+    (uploads_dir / "existing.txt").write_text("hello", encoding="utf-8")
+
+    agent = await asyncio.to_thread(lambda: create_agent(model=_FakeModel(responses=[AIMessage(content="ok")]), tools=[], middleware=[mw]))
+
+    result = await agent.ainvoke(
+        {"messages": [HumanMessage(content="hi")]},
+        {"configurable": {"thread_id": "t1"}},
+    )
+
+    assert result["messages"]
@@ -318,3 +318,76 @@ class TestDownloadFile:
        result = sandbox.download_file("/mnt/user-data/outputs/single.bin")

        assert result == b"single-chunk"
+
+
+class TestClose:
+    """Verify AioSandbox.close() tears down the host-side HTTP client (#2872)."""
+
+    def test_close_calls_real_nested_httpx_client(self, sandbox):
+        """close() must close the real httpx.Client at the bottom of the chain.
+
+        Mirrors the actual Fern structure:
+            Sandbox._client_wrapper.httpx_client  -> Fern HttpClient (no close())
+                .httpx_client                     -> httpx.Client    (the real owner)
+
+        The intermediate HttpClient deliberately exposes NO close(), so a naive
+        one-level lookup (the original bug) would silently close nothing.
+        """
+        real_httpx = MagicMock(spec=["close"])
+        fern_http = SimpleNamespace(httpx_client=real_httpx)  # no close on this layer
+        sandbox._client._client_wrapper = SimpleNamespace(httpx_client=fern_http)
+
+        sandbox.close()
+
+        real_httpx.close.assert_called_once_with()
+
+    def test_close_clears_client_reference(self, sandbox):
+        """After close(), the client reference must be dropped (use-after-close safety)."""
+        real_httpx = MagicMock(spec=["close"])
+        fern_http = SimpleNamespace(httpx_client=real_httpx)
+        sandbox._client._client_wrapper = SimpleNamespace(httpx_client=fern_http)
+
+        sandbox.close()
+
+        assert sandbox._client is None
+        assert sandbox._closed is True
+
+    def test_close_is_idempotent(self, sandbox):
+        """Calling close() multiple times must close the underlying client at most once."""
+        real_httpx = MagicMock(spec=["close"])
+        fern_http = SimpleNamespace(httpx_client=real_httpx)
+        sandbox._client._client_wrapper = SimpleNamespace(httpx_client=fern_http)
+
+        sandbox.close()
+        sandbox.close()
+        sandbox.close()
+
+        assert real_httpx.close.call_count == 1
+
+    def test_close_swallows_exceptions(self, sandbox, caplog):
+        """close() must be best-effort: client errors are logged but never raised."""
+        real_httpx = MagicMock(spec=["close"])
+        real_httpx.close.side_effect = RuntimeError("teardown boom")
+        fern_http = SimpleNamespace(httpx_client=real_httpx)
+        sandbox._client._client_wrapper = SimpleNamespace(httpx_client=fern_http)
+
+        with caplog.at_level("WARNING"):
+            sandbox.close()
+
+        assert "Error closing AioSandbox client" in caplog.text
+
+    def test_close_falls_back_to_client_close(self, sandbox):
+        """If no nested httpx.Client is reachable, close() degrades to the client's own close()."""
+        # Replace the mocked client with a stub that exposes only top-level close()
+        client = MagicMock(spec=["close"])
+        sandbox._client = client
+
+        sandbox.close()
+
+        client.close.assert_called_once_with()
+
+    def test_close_when_no_close_attr_does_not_raise(self, sandbox):
+        """A client without any close attribute must not crash close()."""
+        sandbox._client = SimpleNamespace()  # no close, no _client_wrapper
+        sandbox.close()  # must not raise
+        assert sandbox._client is None
@@ -348,3 +348,89 @@ def test_remote_backend_create_forwards_effective_user_id(monkeypatch):
        "thread_id": "thread-42",
        "user_id": "user-7",
    }
+
+
+# ── Sandbox client teardown (#2872) ──────────────────────────────────────────
+
+
+def _make_provider_with_active_sandbox(tmp_path, sandbox_id: str):
+    """Build a provider with one active sandbox suitable for release/destroy/shutdown tests."""
+    aio_mod = importlib.import_module("deerflow.community.aio_sandbox.aio_sandbox_provider")
+    provider = _make_provider(tmp_path)
+    provider._lock = aio_mod.threading.Lock()
+    provider._warm_pool = {}
+    provider._sandbox_infos = {
+        sandbox_id: aio_mod.SandboxInfo(sandbox_id=sandbox_id, sandbox_url="http://sandbox-host"),
+    }
+    provider._thread_sandboxes = {}
+    provider._last_activity = {sandbox_id: 0.0}
+    provider._shutdown_called = False
+    provider._idle_checker_thread = None
+    provider._backend = SimpleNamespace(destroy=MagicMock())
+
+    sandbox = MagicMock()
+    sandbox.id = sandbox_id
+    sandbox.close = MagicMock()
+    provider._sandboxes = {sandbox_id: sandbox}
+    return provider, sandbox, aio_mod
+
+
+def test_release_closes_cached_sandbox_client(tmp_path):
+    """release() must close the host-side client owned by the cached AioSandbox (#2872)."""
+    provider, sandbox, _ = _make_provider_with_active_sandbox(tmp_path, "sandbox-rel")
+
+    provider.release("sandbox-rel")
+
+    sandbox.close.assert_called_once_with()
+    # And the sandbox is parked in the warm pool (container still running).
+    assert "sandbox-rel" in provider._warm_pool
+    assert "sandbox-rel" not in provider._sandboxes
+
+
+def test_destroy_closes_cached_sandbox_client(tmp_path):
+    """destroy() must close the host-side client before backend container teardown (#2872)."""
+    provider, sandbox, _ = _make_provider_with_active_sandbox(tmp_path, "sandbox-destroy")
+    backend_destroy = provider._backend.destroy
+
+    provider.destroy("sandbox-destroy")
+
+    sandbox.close.assert_called_once_with()
+    backend_destroy.assert_called_once()
+    assert "sandbox-destroy" not in provider._sandboxes
+    assert "sandbox-destroy" not in provider._sandbox_infos
+
+
+def test_shutdown_closes_all_active_sandbox_clients(tmp_path):
+    """shutdown() must close every cached AioSandbox client during teardown (#2872)."""
+    provider, sandbox, _ = _make_provider_with_active_sandbox(tmp_path, "sandbox-shut")
+
+    provider.shutdown()
+
+    sandbox.close.assert_called_once_with()
+    provider._backend.destroy.assert_called_once()
+    assert provider._sandboxes == {}
+
+
+def test_release_swallows_close_errors(tmp_path, caplog):
+    """A failure inside sandbox.close() must not break provider release()."""
+    provider, sandbox, _ = _make_provider_with_active_sandbox(tmp_path, "sandbox-rel-err")
+    sandbox.close.side_effect = RuntimeError("boom")
+
+    with caplog.at_level("WARNING"):
+        provider.release("sandbox-rel-err")
+
+    assert "Error closing sandbox sandbox-rel-err during release" in caplog.text
+    # Still moved to warm pool: client teardown failure must not block lifecycle.
+    assert "sandbox-rel-err" in provider._warm_pool
+
+
+def test_destroy_swallows_close_errors_and_still_destroys_backend(tmp_path, caplog):
+    """A failure in sandbox.close() must not skip backend container destruction."""
+    provider, sandbox, _ = _make_provider_with_active_sandbox(tmp_path, "sandbox-dest-err")
+    sandbox.close.side_effect = RuntimeError("boom")
+
+    with caplog.at_level("WARNING"):
+        provider.destroy("sandbox-dest-err")
+
+    assert "Error closing sandbox sandbox-dest-err during destroy" in caplog.text
+    provider._backend.destroy.assert_called_once()
@@ -0,0 +1,166 @@
+"""Tests for shared assistant payload replay helpers."""
+
+from __future__ import annotations
+
+from langchain_core.messages import AIMessage, HumanMessage
+
+from deerflow.models.assistant_payload_replay import (
+    restore_additional_kwargs_field,
+    restore_assistant_payloads,
+    restore_reasoning_content,
+)
+
+
+def _restore_reasoning(payload_msg: dict, orig_msg: AIMessage) -> None:
+    restore_additional_kwargs_field(payload_msg, orig_msg, "reasoning_content")
+
+
+def test_restore_additional_kwargs_field_copies_present_values_only():
+    payload_message = {"role": "assistant"}
+    orig_message = AIMessage(
+        content="answer",
+        additional_kwargs={
+            "reasoning_content": "",
+            "ignored_none": None,
+        },
+    )
+
+    restore_additional_kwargs_field(payload_message, orig_message, "reasoning_content")
+    restore_additional_kwargs_field(payload_message, orig_message, "ignored_none")
+    restore_additional_kwargs_field(payload_message, orig_message, "missing")
+
+    assert payload_message == {"role": "assistant", "reasoning_content": ""}
+
+
+def test_restore_reasoning_content_copies_reasoning_content():
+    payload_message = {"role": "assistant"}
+    orig_message = AIMessage(content="answer", additional_kwargs={"reasoning_content": "thought"})
+
+    restore_reasoning_content(payload_message, orig_message)
+
+    assert payload_message["reasoning_content"] == "thought"
+
+
+def test_restore_assistant_payloads_matches_by_position_when_lengths_match():
+    original_messages = [
+        HumanMessage(content="question"),
+        AIMessage(content="answer", additional_kwargs={"reasoning_content": "thought"}),
+    ]
+    payload_messages = [
+        {"role": "user", "content": "question"},
+        {"role": "assistant", "content": "answer"},
+    ]
+
+    restore_assistant_payloads(payload_messages, original_messages, _restore_reasoning)
+
+    assert payload_messages[1]["reasoning_content"] == "thought"
+
+
+def test_restore_assistant_payloads_fallback_matches_unique_content_signature():
+    original_messages = [
+        AIMessage(content="first", additional_kwargs={"reasoning_content": "first-thought"}),
+        AIMessage(content="second", additional_kwargs={"reasoning_content": "second-thought"}),
+    ]
+    payload_messages = [{"role": "assistant", "content": "second"}]
+
+    restore_assistant_payloads(payload_messages, original_messages, _restore_reasoning)
+
+    assert payload_messages[0]["reasoning_content"] == "second-thought"
+
+
+def test_restore_assistant_payloads_fallback_matches_unique_tool_call_signature():
+    original_messages = [
+        AIMessage(
+            content="",
+            additional_kwargs={"reasoning_content": "first-thought"},
+            tool_calls=[{"id": "call_first", "name": "tool", "args": {}}],
+        ),
+        AIMessage(
+            content="",
+            additional_kwargs={"reasoning_content": "second-thought"},
+            tool_calls=[{"id": "call_second", "name": "tool", "args": {}}],
+        ),
+    ]
+    payload_messages = [
+        {
+            "role": "assistant",
+            "content": "",
+            "tool_calls": [{"id": "call_second", "type": "function", "function": {"name": "tool", "arguments": "{}"}}],
+        }
+    ]
+
+    restore_assistant_payloads(payload_messages, original_messages, _restore_reasoning)
+
+    assert payload_messages[0]["reasoning_content"] == "second-thought"
+
+
+def test_restore_assistant_payloads_fallback_matches_structured_content_signature():
+    original_messages = [
+        AIMessage(
+            content=[{"type": "text", "text": "first"}],
+            additional_kwargs={"reasoning_content": "first-thought"},
+        ),
+        AIMessage(
+            content=[{"type": "text", "text": "second"}],
+            additional_kwargs={"reasoning_content": "second-thought"},
+        ),
+    ]
+    payload_messages = [{"role": "assistant", "content": [{"text": "second", "type": "text"}]}]
+
+    restore_assistant_payloads(payload_messages, original_messages, _restore_reasoning)
+
+    assert payload_messages[0]["reasoning_content"] == "second-thought"
+
+
+def test_restore_assistant_payloads_fallback_uses_order_when_signature_is_ambiguous():
+    original_messages = [
+        AIMessage(content="", additional_kwargs={"reasoning_content": "first-thought"}),
+        AIMessage(content="", additional_kwargs={"reasoning_content": "second-thought"}),
+    ]
+    payload_messages = [{"role": "assistant", "content": ""}]
+
+    restore_assistant_payloads(payload_messages, original_messages, _restore_reasoning)
+
+    assert payload_messages[0]["reasoning_content"] == "first-thought"
+
+
+def test_restore_assistant_payloads_fallback_uses_next_unused_when_ordinal_taken():
+    # Serialization dropped a leading empty assistant message, so payload ordinals
+    # no longer line up with the original AIMessage indices. The first payload
+    # uniquely matches a non-ordinal index by signature, which leaves the later
+    # ambiguous payload's exact ordinal index already used. It must still fall
+    # back to the remaining unused AIMessage (scanning forward from the ordinal)
+    # instead of silently dropping the field.
+    original_messages = [
+        AIMessage(content="", additional_kwargs={"reasoning_content": "dropped-thought"}),
+        AIMessage(content="unique", additional_kwargs={"reasoning_content": "unique-thought"}),
+        AIMessage(content="", additional_kwargs={"reasoning_content": "trailing-thought"}),
+    ]
+    payload_messages = [
+        {"role": "assistant", "content": "unique"},
+        {"role": "assistant", "content": ""},
+    ]
+
+    restore_assistant_payloads(payload_messages, original_messages, _restore_reasoning)
+
+    assert payload_messages[0]["reasoning_content"] == "unique-thought"
+    # Forward scan from the taken ordinal picks the trailing message, not the
+    # dropped leading one (which a naive min-unused scan would wrongly select).
+    assert payload_messages[1]["reasoning_content"] == "trailing-thought"
+
+
+def test_restore_assistant_payloads_does_not_wrap_to_earlier_unused_message():
+    original_messages = [
+        HumanMessage(content="leading user"),
+        AIMessage(content="", additional_kwargs={"reasoning_content": "dropped-leading-thought"}),
+        AIMessage(content="unique", additional_kwargs={"reasoning_content": "unique-thought"}),
+    ]
+    payload_messages = [
+        {"role": "assistant", "content": "unique"},
+        {"role": "assistant", "content": ""},
+    ]
+
+    restore_assistant_payloads(payload_messages, original_messages, _restore_reasoning)
+
+    assert payload_messages[0]["reasoning_content"] == "unique-thought"
+    assert "reasoning_content" not in payload_messages[1]
@@ -12,7 +12,14 @@ from unittest.mock import AsyncMock, MagicMock, patch
 import pytest

 from app.channels.base import Channel
-from app.channels.message_bus import InboundMessage, InboundMessageType, MessageBus, OutboundMessage, ResolvedAttachment
+from app.channels.message_bus import (
+    PENDING_CLARIFICATION_METADATA_KEY,
+    InboundMessage,
+    InboundMessageType,
+    MessageBus,
+    OutboundMessage,
+    ResolvedAttachment,
+)
 from app.channels.store import ChannelStore


@@ -372,6 +379,66 @@ class TestExtractResponseText:
        # Should return "" (no text in current turn), NOT "Hi there!" from previous turn
        assert _extract_response_text(result) == ""

+    def test_ignores_hidden_human_control_messages(self):
+        """Hidden control messages should not terminate current-turn response extraction."""
+        from app.channels.manager import _extract_response_text
+
+        result = {
+            "messages": [
+                {"type": "human", "content": "plan this"},
+                {"type": "ai", "content": "Here is the plan."},
+                {
+                    "type": "human",
+                    "name": "todo_reminder",
+                    "content": "keep todos updated",
+                    "additional_kwargs": {"hide_from_ui": True},
+                },
+            ]
+        }
+
+        assert _extract_response_text(result) == "Here is the plan."
+
+
+class TestClarificationDetection:
+    def test_final_clarification_tool_message_is_pending(self):
+        from app.channels.manager import _has_current_turn_clarification
+
+        result = {
+            "messages": [
+                {"type": "human", "content": "deploy"},
+                {"type": "ai", "content": "", "tool_calls": [{"name": "ask_clarification", "args": {}}]},
+                {"type": "tool", "name": "ask_clarification", "content": "Which environment?"},
+            ]
+        }
+        assert _has_current_turn_clarification(result) is True
+
+    def test_clarification_followed_by_regular_ai_is_not_pending(self):
+        from app.channels.manager import _has_current_turn_clarification
+
+        result = {
+            "messages": [
+                {"type": "human", "content": "deploy"},
+                {"type": "ai", "content": "", "tool_calls": [{"name": "ask_clarification", "args": {}}]},
+                {"type": "tool", "name": "ask_clarification", "content": "Which environment?"},
+                {"type": "ai", "content": "I will continue without pending clarification."},
+            ]
+        }
+        assert _has_current_turn_clarification(result) is False
+
+    def test_previous_turn_clarification_does_not_mark_current_turn(self):
+        from app.channels.manager import _has_current_turn_clarification
+
+        result = {
+            "messages": [
+                {"type": "human", "content": "deploy"},
+                {"type": "ai", "content": "", "tool_calls": [{"name": "ask_clarification", "args": {}}]},
+                {"type": "tool", "name": "ask_clarification", "content": "Which environment?"},
+                {"type": "human", "content": "prod"},
+                {"type": "ai", "content": "Deploying to prod."},
+            ]
+        }
+        assert _has_current_turn_clarification(result) is False
+

 # ---------------------------------------------------------------------------
 # ChannelManager tests
@@ -618,6 +685,74 @@ class TestChannelManager:

        _run(go())

+    def test_handle_chat_marks_clarification_outbound_metadata(self):
+        from app.channels.manager import ChannelManager
+
+        async def go():
+            bus = MessageBus()
+            store = ChannelStore(path=Path(tempfile.mkdtemp()) / "store.json")
+            manager = ChannelManager(bus=bus, store=store)
+            outbound_received: list[OutboundMessage] = []
+
+            async def capture_outbound(msg: OutboundMessage) -> None:
+                outbound_received.append(msg)
+
+            bus.subscribe_outbound(capture_outbound)
+            mock_client = _make_mock_langgraph_client(
+                run_result={
+                    "messages": [
+                        {"type": "human", "content": "deploy"},
+                        {"type": "ai", "content": "", "tool_calls": [{"name": "ask_clarification", "args": {}}]},
+                        {"type": "tool", "name": "ask_clarification", "content": "Which environment?"},
+                    ]
+                }
+            )
+            manager._client = mock_client
+            await manager.start()
+
+            inbound = InboundMessage(
+                channel_name="test",
+                chat_id="chat1",
+                user_id="user1",
+                text="deploy",
+                metadata={"message_id": "msg-1"},
+            )
+            await bus.publish_inbound(inbound)
+            await _wait_for(lambda: len(outbound_received) >= 1)
+            await manager.stop()
+
+            assert outbound_received[0].text == "Which environment?"
+            assert outbound_received[0].metadata["message_id"] == "msg-1"
+            assert outbound_received[0].metadata[PENDING_CLARIFICATION_METADATA_KEY] is True
+
+        _run(go())
+
+    def test_handle_chat_does_not_mark_regular_outbound_as_clarification(self):
+        from app.channels.manager import ChannelManager
+
+        async def go():
+            bus = MessageBus()
+            store = ChannelStore(path=Path(tempfile.mkdtemp()) / "store.json")
+            manager = ChannelManager(bus=bus, store=store)
+            outbound_received: list[OutboundMessage] = []
+
+            async def capture_outbound(msg: OutboundMessage) -> None:
+                outbound_received.append(msg)
+
+            bus.subscribe_outbound(capture_outbound)
+            mock_client = _make_mock_langgraph_client()
+            manager._client = mock_client
+            await manager.start()
+
+            await bus.publish_inbound(InboundMessage(channel_name="test", chat_id="chat1", user_id="user1", text="hi"))
+            await _wait_for(lambda: len(outbound_received) >= 1)
+            await manager.stop()
+
+            assert outbound_received[0].text == "Hello from agent!"
+            assert PENDING_CLARIFICATION_METADATA_KEY not in outbound_received[0].metadata
+
+        _run(go())
+
    def test_handle_chat_outbound_drops_large_metadata_keys(self):
        """Large metadata keys like raw_message should be stripped from outbound messages."""
        from app.channels.manager import ChannelManager
@@ -999,6 +1134,67 @@ class TestChannelManager:

        _run(go())

+    def test_handle_feishu_streaming_marks_only_final_clarification_outbound(self, monkeypatch):
+        from app.channels.manager import ChannelManager
+
+        monkeypatch.setattr("app.channels.manager.STREAM_UPDATE_MIN_INTERVAL_SECONDS", 0.0)
+
+        async def go():
+            bus = MessageBus()
+            store = ChannelStore(path=Path(tempfile.mkdtemp()) / "store.json")
+            manager = ChannelManager(bus=bus, store=store)
+            outbound_received: list[OutboundMessage] = []
+
+            async def capture_outbound(msg: OutboundMessage) -> None:
+                outbound_received.append(msg)
+
+            bus.subscribe_outbound(capture_outbound)
+            stream_events = [
+                _make_stream_part(
+                    "messages-tuple",
+                    [
+                        {"id": "ai-1", "content": "Thinking", "type": "AIMessageChunk"},
+                        {"langgraph_node": "agent"},
+                    ],
+                ),
+                _make_stream_part(
+                    "values",
+                    {
+                        "messages": [
+                            {"type": "human", "content": "deploy"},
+                            {"type": "ai", "content": "", "tool_calls": [{"name": "ask_clarification", "args": {}}]},
+                            {"type": "tool", "name": "ask_clarification", "content": "Which environment?"},
+                        ],
+                        "artifacts": [],
+                    },
+                ),
+            ]
+            mock_client = _make_mock_langgraph_client()
+            mock_client.runs.stream = MagicMock(return_value=_make_async_iterator(stream_events))
+            manager._client = mock_client
+            await manager.start()
+
+            await bus.publish_inbound(
+                InboundMessage(
+                    channel_name="feishu",
+                    chat_id="chat1",
+                    user_id="user1",
+                    text="deploy",
+                    thread_ts="om-source-1",
+                )
+            )
+            await _wait_for(lambda: len(outbound_received) >= 2)
+            await manager.stop()
+
+            assert [msg.is_final for msg in outbound_received] == [False, False, True]
+            assert outbound_received[0].text == "Thinking"
+            assert outbound_received[1].text == "Which environment?"
+            assert outbound_received[2].text == "Which environment?"
+            assert all(PENDING_CLARIFICATION_METADATA_KEY not in msg.metadata for msg in outbound_received[:-1])
+            assert outbound_received[-1].metadata[PENDING_CLARIFICATION_METADATA_KEY] is True
+
+        _run(go())
+
    def test_handle_feishu_stream_error_still_sends_final(self, monkeypatch):
        """When the stream raises mid-way, a final outbound with is_final=True must still be published."""
        from app.channels.manager import ChannelManager
@@ -1591,6 +1787,51 @@ class TestChannelManager:
        _run(go())


+class TestResolveRunParamsUserId:
+    """Regression for PR #3294: channel identity must reach ``run_context``
+    while staying safe for user-scoped filesystem buckets.
+    """
+
+    def _manager(self):
+        from app.channels.manager import ChannelManager
+
+        bus = MessageBus()
+        store = ChannelStore(path=Path(tempfile.mkdtemp()) / "store.json")
+        return ChannelManager(bus=bus, store=store)
+
+    def test_safe_user_id_is_passed_through(self):
+        manager = self._manager()
+        msg = InboundMessage(channel_name="telegram", chat_id="c", user_id="123456", text="hi")
+
+        _, _, run_context = manager._resolve_run_params(msg, "thread-1")
+
+        assert run_context["user_id"] == "123456"
+        assert run_context["channel_user_id"] == "123456"
+
+    def test_unsafe_user_id_is_normalized_but_raw_preserved(self):
+        from deerflow.config.paths import make_safe_user_id
+
+        manager = self._manager()
+        raw = "user@example.com"
+        msg = InboundMessage(channel_name="feishu", chat_id="c", user_id=raw, text="hi")
+
+        _, _, run_context = manager._resolve_run_params(msg, "thread-1")
+
+        assert run_context["user_id"] == make_safe_user_id(raw)
+        assert run_context["user_id"] != raw
+        assert run_context["channel_user_id"] == raw
+
+    @pytest.mark.parametrize("raw_user_id", ["", None])
+    def test_empty_or_none_user_id_is_not_injected(self, raw_user_id):
+        manager = self._manager()
+        msg = InboundMessage(channel_name="feishu", chat_id="c", user_id=raw_user_id, text="hi")
+
+        _, _, run_context = manager._resolve_run_params(msg, "thread-1")
+
+        assert "user_id" not in run_context
+        assert "channel_user_id" not in run_context
+
+
 # ---------------------------------------------------------------------------
 # ChannelService tests
 # ---------------------------------------------------------------------------
@@ -1678,6 +1919,31 @@ class TestExtractArtifacts:
        }
        assert _extract_artifacts(result) == ["/mnt/user-data/outputs/a.txt", "/mnt/user-data/outputs/b.csv"]

+    def test_ignores_hidden_human_control_messages(self):
+        """Hidden control messages should not hide current-turn present_files artifacts."""
+        from app.channels.manager import _extract_artifacts
+
+        result = {
+            "messages": [
+                {"type": "human", "content": "export"},
+                {
+                    "type": "ai",
+                    "content": "Done.",
+                    "tool_calls": [
+                        {"name": "present_files", "args": {"filepaths": ["/mnt/user-data/outputs/plan.md"]}},
+                    ],
+                },
+                {
+                    "type": "human",
+                    "name": "todo_completion_reminder",
+                    "content": "mark tasks complete",
+                    "additional_kwargs": {"hide_from_ui": True},
+                },
+            ]
+        }
+
+        assert _extract_artifacts(result) == ["/mnt/user-data/outputs/plan.md"]
+

 class TestFormatArtifactText:
    def test_single_artifact(self):
@@ -1790,6 +2056,50 @@ class TestHandleChatWithArtifacts:

        _run(go())

+    def test_hidden_human_control_message_does_not_trigger_no_response_fallback(self):
+        """Plan-mode hidden control messages should not mask the final AI response."""
+        from app.channels.manager import ChannelManager
+
+        async def go():
+            bus = MessageBus()
+            store = ChannelStore(path=Path(tempfile.mkdtemp()) / "store.json")
+            manager = ChannelManager(bus=bus, store=store)
+
+            run_result = {
+                "messages": [
+                    {"type": "human", "content": "make a plan"},
+                    {"type": "ai", "content": "Here is a concrete plan."},
+                    {
+                        "type": "human",
+                        "name": "todo_reminder",
+                        "content": "sync todos",
+                        "additional_kwargs": {"hide_from_ui": True},
+                    },
+                ]
+            }
+            mock_client = _make_mock_langgraph_client(run_result=run_result)
+            manager._client = mock_client
+
+            outbound_received = []
+            bus.subscribe_outbound(lambda msg: outbound_received.append(msg))
+            await manager.start()
+
+            await bus.publish_inbound(
+                InboundMessage(
+                    channel_name="test",
+                    chat_id="c1",
+                    user_id="u1",
+                    text="make a plan",
+                )
+            )
+            await _wait_for(lambda: len(outbound_received) >= 1)
+            await manager.stop()
+
+            assert len(outbound_received) == 1
+            assert outbound_received[0].text == "Here is a concrete plan."
+
+        _run(go())
+
    def test_only_last_turn_artifacts_returned(self):
        """Only artifacts from the current turn's present_files calls should be included."""
        from app.channels.manager import ChannelManager
@@ -1922,7 +2232,8 @@ class TestFeishuChannel:
        async def go():
            bus = MessageBus()
            bus.publish_inbound = AsyncMock()
-            channel = FeishuChannel(bus, config={})
+            store = ChannelStore(path=Path(tempfile.mkdtemp()) / "store.json")
+            channel = FeishuChannel(bus, config={"channel_store": store})
            channel._api_client = MagicMock()

            reply_started = asyncio.Event()
@@ -1958,6 +2269,11 @@ class TestFeishuChannel:
                        text="Hello",
                        is_final=False,
                        thread_ts="om-source-msg",
+                        metadata={
+                            "user_id": "user-1",
+                            "root_id": "om-root-msg",
+                            "topic_id": "om-root-msg",
+                        },
                    )
                )
            )
@@ -1972,6 +2288,9 @@ class TestFeishuChannel:
            assert channel._reply_card.await_count == 1
            channel._update_card.assert_awaited_once_with("om-running-card", "Hello")
            assert "om-source-msg" not in channel._running_card_tasks
+            assert store.get_thread_id("feishu", "chat-1", topic_id="om-source-msg") == "thread-1"
+            assert store.get_thread_id("feishu", "chat-1", topic_id="om-running-card") == "thread-1"
+            assert store.get_thread_id("feishu", "chat-1", topic_id="om-root-msg") == "thread-1"

        _run(go())

@@ -326,6 +326,99 @@ class TestAsyncCheckpointer:
        mock_saver_cls.from_conn_string.assert_called_once_with("/tmp/resolved/test.db")
        mock_saver.setup.assert_awaited_once()

+    @pytest.mark.anyio
+    async def test_postgres_uses_connection_pool(self):
+        """Async postgres checkpointer should use AsyncConnectionPool, not a single connection."""
+        from deerflow.runtime.checkpointer.async_provider import make_checkpointer
+
+        mock_config = MagicMock()
+        mock_config.checkpointer = CheckpointerConfig(type="postgres", connection_string="postgresql://localhost/db")
+
+        mock_saver = AsyncMock()
+
+        mock_saver_cls = MagicMock(return_value=mock_saver)
+
+        mock_pool_instance = AsyncMock()
+        mock_pool_instance.__aenter__.return_value = mock_pool_instance
+        mock_pool_instance.__aexit__.return_value = False
+
+        mock_pool_cls = MagicMock(return_value=mock_pool_instance)
+        mock_pool_cls.check_connection = AsyncMock()
+        mock_dict_row = MagicMock()
+
+        mock_pg_module = MagicMock()
+        mock_pg_module.AsyncPostgresSaver = mock_saver_cls
+
+        mock_psycopg_rows = MagicMock()
+        mock_psycopg_rows.dict_row = mock_dict_row
+
+        with (
+            patch("deerflow.runtime.checkpointer.async_provider.get_app_config", return_value=mock_config),
+            patch.dict(sys.modules, {"langgraph.checkpoint.postgres.aio": mock_pg_module}),
+            patch.dict(sys.modules, {"psycopg.rows": mock_psycopg_rows}),
+            patch.dict(sys.modules, {"psycopg_pool": MagicMock(AsyncConnectionPool=mock_pool_cls)}),
+        ):
+            # AsyncConnectionPool() is a callable that returns mock_pool_instance
+            # We need the constructor to be an async context manager
+            async with make_checkpointer() as saver:
+                assert saver is mock_saver
+
+        # Verify the pool was constructed with check Connection
+        mock_pool_cls.assert_called_once()
+        call_kwargs = mock_pool_cls.call_args
+        assert call_kwargs[0][0] == "postgresql://localhost/db"
+        assert call_kwargs[1]["check"] is mock_pool_cls.check_connection
+
+        # Verify saver was constructed with the pool (not via from_conn_string)
+        mock_saver_cls.assert_called_once_with(conn=mock_pool_instance)
+        mock_saver.setup.assert_awaited_once()
+
+    @pytest.mark.anyio
+    async def test_database_postgres_uses_connection_pool(self):
+        """Unified database postgres path should use AsyncConnectionPool with keepalive."""
+        from deerflow.config.database_config import DatabaseConfig
+        from deerflow.runtime.checkpointer.async_provider import make_checkpointer
+
+        db_config = DatabaseConfig(backend="postgres", postgres_url="postgresql://localhost/db")
+        mock_config = MagicMock()
+        mock_config.checkpointer = None
+        mock_config.database = db_config
+
+        mock_saver = AsyncMock()
+
+        mock_saver_cls = MagicMock(return_value=mock_saver)
+
+        mock_pool_instance = AsyncMock()
+        mock_pool_instance.__aenter__.return_value = mock_pool_instance
+        mock_pool_instance.__aexit__.return_value = False
+
+        mock_pool_cls = MagicMock(return_value=mock_pool_instance)
+        mock_pool_cls.check_connection = AsyncMock()
+        mock_dict_row = MagicMock()
+
+        mock_pg_module = MagicMock()
+        mock_pg_module.AsyncPostgresSaver = mock_saver_cls
+
+        mock_psycopg_rows = MagicMock()
+        mock_psycopg_rows.dict_row = mock_dict_row
+
+        with (
+            patch("deerflow.runtime.checkpointer.async_provider.get_app_config", return_value=mock_config),
+            patch.dict(sys.modules, {"langgraph.checkpoint.postgres.aio": mock_pg_module}),
+            patch.dict(sys.modules, {"psycopg.rows": mock_psycopg_rows}),
+            patch.dict(sys.modules, {"psycopg_pool": MagicMock(AsyncConnectionPool=mock_pool_cls)}),
+        ):
+            async with make_checkpointer() as saver:
+                assert saver is mock_saver
+
+        mock_pool_cls.assert_called_once()
+        call_kwargs = mock_pool_cls.call_args
+        assert call_kwargs[0][0] == "postgresql://localhost/db"
+        assert call_kwargs[1]["check"] is mock_pool_cls.check_connection
+
+        mock_saver_cls.assert_called_once_with(conn=mock_pool_instance)
+        mock_saver.setup.assert_awaited_once()
+
    @pytest.mark.anyio
    async def test_database_sqlite_creates_parent_dir_via_to_thread(self):
        """Unified database SQLite setup should also move path IO off the event loop."""
@@ -1472,6 +1472,7 @@ class TestUploads:
            assert result["success"] is True
            assert len(result["files"]) == 1
            assert result["files"][0]["filename"] == "test.txt"
+            assert result["files"][0]["size"] == len("hello")
            assert "artifact_url" in result["files"][0]
            assert "message" in result
            assert (uploads_dir / "test.txt").exists()
@@ -1551,6 +1552,8 @@ class TestUploads:
            assert len(result["files"]) == 2
            names = {f["filename"] for f in result["files"]}
            assert names == {"a.txt", "b.txt"}
+            sizes = {f["filename"]: f["size"] for f in result["files"]}
+            assert sizes == {"a.txt": 1, "b.txt": 2}
            # Verify artifact_url is present
            for f in result["files"]:
                assert "artifact_url" in f
@@ -2458,6 +2461,7 @@ class TestGatewayConformance:
        parsed = UploadResponse(**result)
        assert parsed.success is True
        assert len(parsed.files) == 1
+        assert parsed.files[0].size == len("hello")

    def test_get_memory_config(self, client):
        mem_cfg = MagicMock()
@@ -333,8 +333,27 @@ class TestBuildPatchedMessagesPatching:
        assert patched[1].tool_call_id == "write_file:36"
        assert patched[1].name == "write_file"
        assert patched[1].status == "error"
+        assert "write_file failed before execution" in patched[1].content
+        assert "no file was written" in patched[1].content
+        assert "very large Markdown file in a single tool call" in patched[1].content
+        assert "Do not retry the same large `write_file` payload" in patched[1].content
+        assert "split the file into smaller sections" in patched[1].content
+        assert "normal assistant text" in patched[1].content
+        assert "Failed to parse tool arguments" in patched[1].content
+        assert 'bad {"json"}' not in patched[1].content
+
+    def test_non_write_file_invalid_tool_call_uses_generic_recovery_message(self):
+        mw = DanglingToolCallMiddleware()
+        msgs = [_ai_with_invalid_tool_calls([_invalid_tc(name="search", tc_id="search:1")])]
+
+        patched = mw._build_patched_messages(msgs)
+
+        assert patched is not None
+        assert patched[1].tool_call_id == "search:1"
+        assert patched[1].name == "search"
        assert "arguments were invalid" in patched[1].content
        assert "Failed to parse tool arguments" in patched[1].content
+        assert "write_file failed before execution" not in patched[1].content

    def test_valid_and_invalid_tool_calls_are_both_patched(self):
        mw = DanglingToolCallMiddleware()
@@ -0,0 +1,83 @@
+import pytest
+from langchain_core.tools import tool as as_tool
+
+from deerflow.tools.builtins.tool_search import DeferredToolCatalog
+
+
+@as_tool
+def alpha_search(query: str) -> str:
+    "Search alpha records by query."
+    return query
+
+
+@as_tool
+def beta_translate(text: str) -> str:
+    "Translate beta text."
+    return text
+
+
+@pytest.fixture
+def catalog() -> DeferredToolCatalog:
+    return DeferredToolCatalog((alpha_search, beta_translate))
+
+
+def test_names(catalog):
+    assert catalog.names == frozenset({"alpha_search", "beta_translate"})
+
+
+def test_search_select(catalog):
+    got = catalog.search("select:alpha_search")
+    assert [t.name for t in got] == ["alpha_search"]
+
+
+def test_search_plus_keyword(catalog):
+    got = catalog.search("+beta translate")
+    assert [t.name for t in got] == ["beta_translate"]
+
+
+def test_search_regex_on_description(catalog):
+    got = catalog.search("translate")
+    assert "beta_translate" in [t.name for t in got]
+
+
+def test_search_invalid_regex_falls_back_to_literal():
+    @as_tool
+    def calc(expr: str) -> str:
+        "Compute sum(a, b) style expressions."
+        return expr
+
+    cat = DeferredToolCatalog((calc, alpha_search))
+    # "sum(" is an invalid regex (unbalanced paren). search() must not raise; it
+    # falls back to a literal match, which finds calc's "sum(" in its description.
+    assert [t.name for t in cat.search("sum(")] == ["calc"]
+    # A literal with no match is deterministically empty (and still must not raise).
+    assert cat.search("zzz(") == []
+
+
+def test_search_empty_query_returns_empty(catalog):
+    # An empty / whitespace-only query is meaningless; rather than let the empty
+    # regex match every tool, search() returns nothing so the model gets a clear
+    # "no match" signal and re-queries instead of acting on noise.
+    assert catalog.search("") == []
+    assert catalog.search("   ") == []
+
+
+def test_search_bare_plus_returns_empty(catalog):
+    # A "+" prefix with no required token is malformed model input. It must
+    # return no matches, not raise IndexError on parts[0]. " + " strips to "+",
+    # so it routes here too and must be handled the same way.
+    assert catalog.search("+") == []
+    assert catalog.search(" + ") == []
+    assert catalog.search("+   ") == []
+
+
+def test_hash_stable_across_instances():
+    c1 = DeferredToolCatalog((alpha_search, beta_translate))
+    c2 = DeferredToolCatalog((beta_translate, alpha_search))
+    assert c1.hash == c2.hash
+
+
+def test_hash_changes_with_membership():
+    c1 = DeferredToolCatalog((alpha_search, beta_translate))
+    c2 = DeferredToolCatalog((alpha_search,))
+    assert c1.hash != c2.hash
@@ -0,0 +1,87 @@
+"""Tests for DeferredToolFilterMiddleware (closure deferred-set + state promotion)."""
+
+from langchain_core.tools import tool as as_tool
+
+from deerflow.agents.middlewares.deferred_tool_filter_middleware import DeferredToolFilterMiddleware
+
+
+@as_tool
+def mcp_a(x: str) -> str:
+    "a"
+    return x
+
+
+@as_tool
+def mcp_b(x: str) -> str:
+    "b"
+    return x
+
+
+@as_tool
+def active_c(x: str) -> str:
+    "c"
+    return x
+
+
+class _Req:
+    def __init__(self, tools, state):
+        self.tools = tools
+        self.state = state
+        self.overridden = None
+
+    def override(self, tools):
+        self.overridden = tools
+        return self
+
+
+def _mw():
+    return DeferredToolFilterMiddleware(frozenset({"mcp_a", "mcp_b"}), "h1")
+
+
+def test_hides_all_deferred_when_no_promotion():
+    req = _Req([mcp_a, mcp_b, active_c], {})
+    out = _mw()._filter_tools(req)
+    assert [t.name for t in out.overridden] == ["active_c"]
+
+
+def test_promoted_under_matching_hash_passes_through():
+    req = _Req([mcp_a, mcp_b, active_c], {"promoted": {"catalog_hash": "h1", "names": ["mcp_a"]}})
+    out = _mw()._filter_tools(req)
+    assert {t.name for t in out.overridden} == {"mcp_a", "active_c"}
+
+
+def test_promotion_ignored_when_hash_mismatch():
+    req = _Req([mcp_a, mcp_b, active_c], {"promoted": {"catalog_hash": "STALE", "names": ["mcp_a"]}})
+    out = _mw()._filter_tools(req)
+    assert [t.name for t in out.overridden] == ["active_c"]
+
+
+def test_no_deferred_names_is_noop():
+    req = _Req([active_c], {})
+    out = DeferredToolFilterMiddleware(frozenset(), "h1")._filter_tools(req)
+    assert out.overridden is None  # returned unchanged
+
+
+def test_blocked_message_for_unpromoted_deferred_call():
+    class _TCReq:
+        tool_call = {"name": "mcp_a", "id": "tc1"}
+        state = {}
+
+    msg = _mw()._blocked_tool_message(_TCReq())
+    assert msg is not None and msg.status == "error" and "tool_search" in msg.content
+
+
+def test_no_block_for_promoted_call():
+    class _TCReq:
+        tool_call = {"name": "mcp_a", "id": "tc1"}
+        state = {"promoted": {"catalog_hash": "h1", "names": ["mcp_a"]}}
+
+    assert _mw()._blocked_tool_message(_TCReq()) is None
+
+
+def test_no_block_for_non_deferred_call():
+    class _TCReq:
+        tool_call = {"name": "active_c", "id": "tc1"}
+        state = {}
+
+    assert _mw()._blocked_tool_message(_TCReq()) is None
--- a/Show More
+++ b/Show More