Merge branch 'main' into rayhpeng/persistence-scaffold

# Conflicts:
#	backend/Dockerfile
#	backend/uv.lock

backend/tests/test_channels.py

@@ -7,7 +7,7 @@ import json
 import tempfile
 from pathlib import Path
 from types import SimpleNamespace
-from unittest.mock import AsyncMock, MagicMock
+from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 
@@ -1988,6 +1988,47 @@ class TestSlackSendRetry:
 
         _run(go())
 
+
+class TestSlackAllowedUsers:
+    def test_numeric_allowed_users_match_string_event_user_id(self):
+        from app.channels.slack import SlackChannel
+
+        bus = MessageBus()
+        bus.publish_inbound = AsyncMock()
+        channel = SlackChannel(
+            bus=bus,
+            config={"allowed_users": [123456]},
+        )
+        channel._loop = MagicMock()
+        channel._loop.is_running.return_value = True
+        channel._add_reaction = MagicMock()
+        channel._send_running_reply = MagicMock()
+
+        event = {
+            "user": "123456",
+            "text": "hello from slack",
+            "channel": "C123",
+            "ts": "1710000000.000100",
+        }
+
+        def submit_coro(coro, loop):
+            coro.close()
+            return MagicMock()
+
+        with patch(
+            "app.channels.slack.asyncio.run_coroutine_threadsafe",
+            side_effect=submit_coro,
+        ) as submit:
+            channel._handle_message_event(event)
+
+        channel._add_reaction.assert_called_once_with("C123", "1710000000.000100", "eyes")
+        channel._send_running_reply.assert_called_once_with("C123", "1710000000.000100")
+        submit.assert_called_once()
+        inbound = bus.publish_inbound.call_args.args[0]
+        assert inbound.user_id == "123456"
+        assert inbound.chat_id == "C123"
+        assert inbound.text == "hello from slack"
+
     def test_raises_after_all_retries_exhausted(self):
         from app.channels.slack import SlackChannel
 

backend/tests/test_custom_agent.py

@@ -439,6 +439,15 @@ class TestAgentsAPI:
         assert "agent-one" in names
         assert "agent-two" in names
 
+    def test_list_agents_includes_soul(self, agent_client):
+        agent_client.post("/api/agents", json={"name": "soul-agent", "soul": "My soul content"})
+
+        response = agent_client.get("/api/agents")
+        assert response.status_code == 200
+        agents = response.json()["agents"]
+        soul_agent = next(a for a in agents if a["name"] == "soul-agent")
+        assert soul_agent["soul"] == "My soul content"
+
     def test_get_agent(self, agent_client):
         agent_client.post("/api/agents", json={"name": "test-agent", "soul": "Hello world"})
 

backend/tests/test_memory_queue.py

@@ -47,4 +47,45 @@ def test_process_queue_forwards_correction_flag_to_updater() -> None:
         thread_id="thread-1",
         agent_name="lead_agent",
         correction_detected=True,
+        reinforcement_detected=False,
+    )
+
+
+def test_queue_add_preserves_existing_reinforcement_flag_for_same_thread() -> None:
+    queue = MemoryUpdateQueue()
+
+    with (
+        patch("deerflow.agents.memory.queue.get_memory_config", return_value=_memory_config(enabled=True)),
+        patch.object(queue, "_reset_timer"),
+    ):
+        queue.add(thread_id="thread-1", messages=["first"], reinforcement_detected=True)
+        queue.add(thread_id="thread-1", messages=["second"], reinforcement_detected=False)
+
+    assert len(queue._queue) == 1
+    assert queue._queue[0].messages == ["second"]
+    assert queue._queue[0].reinforcement_detected is True
+
+
+def test_process_queue_forwards_reinforcement_flag_to_updater() -> None:
+    queue = MemoryUpdateQueue()
+    queue._queue = [
+        ConversationContext(
+            thread_id="thread-1",
+            messages=["conversation"],
+            agent_name="lead_agent",
+            reinforcement_detected=True,
+        )
+    ]
+    mock_updater = MagicMock()
+    mock_updater.update_memory.return_value = True
+
+    with patch("deerflow.agents.memory.updater.MemoryUpdater", return_value=mock_updater):
+        queue._process_queue()
+
+    mock_updater.update_memory.assert_called_once_with(
+        messages=["conversation"],
+        thread_id="thread-1",
+        agent_name="lead_agent",
+        correction_detected=False,
+        reinforcement_detected=True,
     )

backend/tests/test_memory_updater.py

@@ -619,3 +619,156 @@ class TestUpdateMemoryStructuredResponse:
         assert result is True
         prompt = model.invoke.call_args[0][0]
         assert "Explicit correction signals were detected" not in prompt
+
+
+class TestFactDeduplicationCaseInsensitive:
+    """Tests that fact deduplication is case-insensitive."""
+
+    def test_duplicate_fact_different_case_not_stored(self):
+        updater = MemoryUpdater()
+        current_memory = _make_memory(
+            facts=[
+                {
+                    "id": "fact_1",
+                    "content": "User prefers Python",
+                    "category": "preference",
+                    "confidence": 0.9,
+                    "createdAt": "2026-01-01T00:00:00Z",
+                    "source": "thread-a",
+                },
+            ]
+        )
+        # Same fact with different casing should be treated as duplicate
+        update_data = {
+            "factsToRemove": [],
+            "newFacts": [
+                {"content": "user prefers python", "category": "preference", "confidence": 0.95},
+            ],
+        }
+
+        with patch(
+            "deerflow.agents.memory.updater.get_memory_config",
+            return_value=_memory_config(max_facts=100, fact_confidence_threshold=0.7),
+        ):
+            result = updater._apply_updates(current_memory, update_data, thread_id="thread-b")
+
+        # Should still have only 1 fact (duplicate rejected)
+        assert len(result["facts"]) == 1
+        assert result["facts"][0]["content"] == "User prefers Python"
+
+    def test_unique_fact_different_case_and_content_stored(self):
+        updater = MemoryUpdater()
+        current_memory = _make_memory(
+            facts=[
+                {
+                    "id": "fact_1",
+                    "content": "User prefers Python",
+                    "category": "preference",
+                    "confidence": 0.9,
+                    "createdAt": "2026-01-01T00:00:00Z",
+                    "source": "thread-a",
+                },
+            ]
+        )
+        update_data = {
+            "factsToRemove": [],
+            "newFacts": [
+                {"content": "User prefers Go", "category": "preference", "confidence": 0.85},
+            ],
+        }
+
+        with patch(
+            "deerflow.agents.memory.updater.get_memory_config",
+            return_value=_memory_config(max_facts=100, fact_confidence_threshold=0.7),
+        ):
+            result = updater._apply_updates(current_memory, update_data, thread_id="thread-b")
+
+        assert len(result["facts"]) == 2
+
+
+class TestReinforcementHint:
+    """Tests that reinforcement_detected injects the correct hint into the prompt."""
+
+    @staticmethod
+    def _make_mock_model(json_response: str):
+        model = MagicMock()
+        response = MagicMock()
+        response.content = f"```json\n{json_response}\n```"
+        model.invoke.return_value = response
+        return model
+
+    def test_reinforcement_hint_injected_when_detected(self):
+        updater = MemoryUpdater()
+        valid_json = '{"user": {}, "history": {}, "newFacts": [], "factsToRemove": []}'
+        model = self._make_mock_model(valid_json)
+
+        with (
+            patch.object(updater, "_get_model", return_value=model),
+            patch("deerflow.agents.memory.updater.get_memory_config", return_value=_memory_config(enabled=True)),
+            patch("deerflow.agents.memory.updater.get_memory_data", return_value=_make_memory()),
+            patch("deerflow.agents.memory.updater.get_memory_storage", return_value=MagicMock(save=MagicMock(return_value=True))),
+        ):
+            msg = MagicMock()
+            msg.type = "human"
+            msg.content = "Yes, exactly! That's what I needed."
+            ai_msg = MagicMock()
+            ai_msg.type = "ai"
+            ai_msg.content = "Great to hear!"
+            ai_msg.tool_calls = []
+
+            result = updater.update_memory([msg, ai_msg], reinforcement_detected=True)
+
+        assert result is True
+        prompt = model.invoke.call_args[0][0]
+        assert "Positive reinforcement signals were detected" in prompt
+
+    def test_reinforcement_hint_absent_when_not_detected(self):
+        updater = MemoryUpdater()
+        valid_json = '{"user": {}, "history": {}, "newFacts": [], "factsToRemove": []}'
+        model = self._make_mock_model(valid_json)
+
+        with (
+            patch.object(updater, "_get_model", return_value=model),
+            patch("deerflow.agents.memory.updater.get_memory_config", return_value=_memory_config(enabled=True)),
+            patch("deerflow.agents.memory.updater.get_memory_data", return_value=_make_memory()),
+            patch("deerflow.agents.memory.updater.get_memory_storage", return_value=MagicMock(save=MagicMock(return_value=True))),
+        ):
+            msg = MagicMock()
+            msg.type = "human"
+            msg.content = "Tell me more."
+            ai_msg = MagicMock()
+            ai_msg.type = "ai"
+            ai_msg.content = "Sure."
+            ai_msg.tool_calls = []
+
+            result = updater.update_memory([msg, ai_msg], reinforcement_detected=False)
+
+        assert result is True
+        prompt = model.invoke.call_args[0][0]
+        assert "Positive reinforcement signals were detected" not in prompt
+
+    def test_both_hints_present_when_both_detected(self):
+        updater = MemoryUpdater()
+        valid_json = '{"user": {}, "history": {}, "newFacts": [], "factsToRemove": []}'
+        model = self._make_mock_model(valid_json)
+
+        with (
+            patch.object(updater, "_get_model", return_value=model),
+            patch("deerflow.agents.memory.updater.get_memory_config", return_value=_memory_config(enabled=True)),
+            patch("deerflow.agents.memory.updater.get_memory_data", return_value=_make_memory()),
+            patch("deerflow.agents.memory.updater.get_memory_storage", return_value=MagicMock(save=MagicMock(return_value=True))),
+        ):
+            msg = MagicMock()
+            msg.type = "human"
+            msg.content = "No wait, that's wrong. Actually yes, exactly right."
+            ai_msg = MagicMock()
+            ai_msg.type = "ai"
+            ai_msg.content = "Got it."
+            ai_msg.tool_calls = []
+
+            result = updater.update_memory([msg, ai_msg], correction_detected=True, reinforcement_detected=True)
+
+        assert result is True
+        prompt = model.invoke.call_args[0][0]
+        assert "Explicit correction signals were detected" in prompt
+        assert "Positive reinforcement signals were detected" in prompt

backend/tests/test_memory_upload_filtering.py

@@ -10,7 +10,7 @@ persisting in long-term memory:
 from langchain_core.messages import AIMessage, HumanMessage, ToolMessage
 
 from deerflow.agents.memory.updater import _strip_upload_mentions_from_memory
-from deerflow.agents.middlewares.memory_middleware import _filter_messages_for_memory, detect_correction
+from deerflow.agents.middlewares.memory_middleware import _filter_messages_for_memory, detect_correction, detect_reinforcement
 
 # ---------------------------------------------------------------------------
 # Helpers
@@ -270,3 +270,73 @@ class TestStripUploadMentionsFromMemory:
         mem = {"user": {}, "history": {}, "facts": []}
         result = _strip_upload_mentions_from_memory(mem)
         assert result == {"user": {}, "history": {}, "facts": []}
+
+
+# ===========================================================================
+# detect_reinforcement
+# ===========================================================================
+
+
+class TestDetectReinforcement:
+    def test_detects_english_reinforcement_signal(self):
+        msgs = [
+            _human("Can you summarise it in bullet points?"),
+            _ai("Here are the key points: ..."),
+            _human("Yes, exactly! That's what I needed."),
+            _ai("Glad it helped."),
+        ]
+
+        assert detect_reinforcement(msgs) is True
+
+    def test_detects_perfect_signal(self):
+        msgs = [
+            _human("Write it more concisely."),
+            _ai("Here is the concise version."),
+            _human("Perfect."),
+            _ai("Great!"),
+        ]
+
+        assert detect_reinforcement(msgs) is True
+
+    def test_detects_chinese_reinforcement_signal(self):
+        msgs = [
+            _human("帮我用要点来总结"),
+            _ai("好的，要点如下：..."),
+            _human("完全正确，就是这个意思"),
+            _ai("很高兴能帮到你"),
+        ]
+
+        assert detect_reinforcement(msgs) is True
+
+    def test_returns_false_without_signal(self):
+        msgs = [
+            _human("What does this function do?"),
+            _ai("It processes the input data."),
+            _human("Can you show me an example?"),
+        ]
+
+        assert detect_reinforcement(msgs) is False
+
+    def test_only_checks_recent_messages(self):
+        # Reinforcement signal buried beyond the -6 window should not trigger
+        msgs = [
+            _human("Yes, exactly right."),
+            _ai("Noted."),
+            _human("Let's discuss tests."),
+            _ai("Sure."),
+            _human("What about linting?"),
+            _ai("Use ruff."),
+            _human("And formatting?"),
+            _ai("Use make format."),
+        ]
+
+        assert detect_reinforcement(msgs) is False
+
+    def test_does_not_conflict_with_correction(self):
+        # A message can trigger correction but not reinforcement
+        msgs = [
+            _human("That's wrong, try again."),
+            _ai("Corrected."),
+        ]
+
+        assert detect_reinforcement(msgs) is False

backend/tests/test_sandbox_tools_security.py

@@ -42,6 +42,53 @@ def test_replace_virtual_path_maps_virtual_root_and_subpaths() -> None:
     assert Path(replace_virtual_path("/mnt/user-data", _THREAD_DATA)).as_posix() == "/tmp/deer-flow/threads/t1/user-data"
 
 
+def test_replace_virtual_path_preserves_trailing_slash() -> None:
+    """Trailing slash must survive virtual-to-actual path replacement.
+
+    Regression: '/mnt/user-data/workspace/' was previously returned without
+    the trailing slash, causing string concatenations like
+    output_dir + 'file.txt' to produce a missing-separator path.
+    """
+    result = replace_virtual_path("/mnt/user-data/workspace/", _THREAD_DATA)
+    assert result.endswith("/"), f"Expected trailing slash, got: {result!r}"
+    assert result == "/tmp/deer-flow/threads/t1/user-data/workspace/"
+
+
+def test_replace_virtual_path_preserves_trailing_slash_windows_style() -> None:
+    """Trailing slash must be preserved as backslash when actual_base is Windows-style.
+
+    If actual_base uses backslash separators, appending '/' would produce a
+    mixed-separator path.  The separator must match the style of actual_base.
+    """
+    win_thread_data = {
+        "workspace_path": r"C:\deer-flow\threads\t1\user-data\workspace",
+        "uploads_path": r"C:\deer-flow\threads\t1\user-data\uploads",
+        "outputs_path": r"C:\deer-flow\threads\t1\user-data\outputs",
+    }
+    result = replace_virtual_path("/mnt/user-data/workspace/", win_thread_data)
+    assert result.endswith("\\"), f"Expected trailing backslash for Windows path, got: {result!r}"
+    assert "/" not in result, f"Mixed separators in Windows path: {result!r}"
+
+
+def test_replace_virtual_path_preserves_windows_style_for_nested_subdir_trailing_slash() -> None:
+    """Nested Windows-style subdirectories must keep backslashes throughout."""
+    win_thread_data = {
+        "workspace_path": r"C:\deer-flow\threads\t1\user-data\workspace",
+        "uploads_path": r"C:\deer-flow\threads\t1\user-data\uploads",
+        "outputs_path": r"C:\deer-flow\threads\t1\user-data\outputs",
+    }
+    result = replace_virtual_path("/mnt/user-data/workspace/subdir/", win_thread_data)
+    assert result == "C:\\deer-flow\\threads\\t1\\user-data\\workspace\\subdir\\"
+    assert "/" not in result, f"Mixed separators in Windows path: {result!r}"
+
+
+def test_replace_virtual_paths_in_command_preserves_trailing_slash() -> None:
+    """Trailing slash on a virtual path inside a command must be preserved."""
+    cmd = """python -c "output_dir = '/mnt/user-data/workspace/'; print(output_dir + 'some_file.txt')\""""
+    result = replace_virtual_paths_in_command(cmd, _THREAD_DATA)
+    assert "/tmp/deer-flow/threads/t1/user-data/workspace/" in result, f"Trailing slash lost in: {result!r}"
+
+
 # ---------- mask_local_paths_in_output ----------
 
 
@@ -257,6 +304,22 @@ def test_validate_local_bash_command_paths_blocks_host_paths() -> None:
         validate_local_bash_command_paths("cat /etc/passwd", _THREAD_DATA)
 
 
+def test_validate_local_bash_command_paths_allows_https_urls() -> None:
+    """URLs like https://github.com/... must not be flagged as unsafe absolute paths."""
+    validate_local_bash_command_paths(
+        "cd /mnt/user-data/workspace && git clone https://github.com/CherryHQ/cherry-studio.git",
+        _THREAD_DATA,
+    )
+
+
+def test_validate_local_bash_command_paths_allows_http_urls() -> None:
+    """HTTP URLs must not be flagged as unsafe absolute paths."""
+    validate_local_bash_command_paths(
+        "curl http://example.com/file.tar.gz -o /mnt/user-data/workspace/file.tar.gz",
+        _THREAD_DATA,
+    )
+
+
 def test_validate_local_bash_command_paths_allows_virtual_and_system_paths() -> None:
     validate_local_bash_command_paths(
         "/bin/echo ok > /mnt/user-data/workspace/out.txt && cat /dev/null",

backend/tests/test_subagent_timeout_config.py

@@ -1,8 +1,8 @@
-"""Tests for subagent timeout configuration.
+"""Tests for subagent runtime configuration.
 
 Covers:
 - SubagentsAppConfig / SubagentOverrideConfig model validation and defaults
-- get_timeout_for() resolution logic (global vs per-agent)
+- get_timeout_for() / get_max_turns_for() resolution logic
 - load_subagents_config_from_dict() and get_subagents_app_config() singleton
 - registry.get_subagent_config() applies config overrides
 - registry.list_subagents() applies overrides for all agents
@@ -24,9 +24,20 @@ from deerflow.subagents.config import SubagentConfig
 # ---------------------------------------------------------------------------
 
 
-def _reset_subagents_config(timeout_seconds: int = 900, agents: dict | None = None) -> None:
+def _reset_subagents_config(
+    timeout_seconds: int = 900,
+    *,
+    max_turns: int | None = None,
+    agents: dict | None = None,
+) -> None:
     """Reset global subagents config to a known state."""
-    load_subagents_config_from_dict({"timeout_seconds": timeout_seconds, "agents": agents or {}})
+    load_subagents_config_from_dict(
+        {
+            "timeout_seconds": timeout_seconds,
+            "max_turns": max_turns,
+            "agents": agents or {},
+        }
+    )
 
 
 # ---------------------------------------------------------------------------
@@ -38,22 +49,29 @@ class TestSubagentOverrideConfig:
     def test_default_is_none(self):
         override = SubagentOverrideConfig()
         assert override.timeout_seconds is None
+        assert override.max_turns is None
 
     def test_explicit_value(self):
-        override = SubagentOverrideConfig(timeout_seconds=300)
+        override = SubagentOverrideConfig(timeout_seconds=300, max_turns=42)
         assert override.timeout_seconds == 300
+        assert override.max_turns == 42
 
     def test_rejects_zero(self):
         with pytest.raises(ValueError):
             SubagentOverrideConfig(timeout_seconds=0)
+        with pytest.raises(ValueError):
+            SubagentOverrideConfig(max_turns=0)
 
     def test_rejects_negative(self):
         with pytest.raises(ValueError):
             SubagentOverrideConfig(timeout_seconds=-1)
+        with pytest.raises(ValueError):
+            SubagentOverrideConfig(max_turns=-1)
 
     def test_minimum_valid_value(self):
-        override = SubagentOverrideConfig(timeout_seconds=1)
+        override = SubagentOverrideConfig(timeout_seconds=1, max_turns=1)
         assert override.timeout_seconds == 1
+        assert override.max_turns == 1
 
 
 # ---------------------------------------------------------------------------
@@ -66,66 +84,86 @@ class TestSubagentsAppConfigDefaults:
         config = SubagentsAppConfig()
         assert config.timeout_seconds == 900
 
+    def test_default_max_turns_override_is_none(self):
+        config = SubagentsAppConfig()
+        assert config.max_turns is None
+
     def test_default_agents_empty(self):
         config = SubagentsAppConfig()
         assert config.agents == {}
 
-    def test_custom_global_timeout(self):
-        config = SubagentsAppConfig(timeout_seconds=1800)
+    def test_custom_global_runtime_overrides(self):
+        config = SubagentsAppConfig(timeout_seconds=1800, max_turns=120)
         assert config.timeout_seconds == 1800
+        assert config.max_turns == 120
 
     def test_rejects_zero_timeout(self):
         with pytest.raises(ValueError):
             SubagentsAppConfig(timeout_seconds=0)
+        with pytest.raises(ValueError):
+            SubagentsAppConfig(max_turns=0)
 
     def test_rejects_negative_timeout(self):
         with pytest.raises(ValueError):
             SubagentsAppConfig(timeout_seconds=-60)
+        with pytest.raises(ValueError):
+            SubagentsAppConfig(max_turns=-60)
 
 
 # ---------------------------------------------------------------------------
-# SubagentsAppConfig.get_timeout_for()
+# SubagentsAppConfig resolution helpers
 # ---------------------------------------------------------------------------
 
 
-class TestGetTimeoutFor:
+class TestRuntimeResolution:
     def test_returns_global_default_when_no_override(self):
         config = SubagentsAppConfig(timeout_seconds=600)
         assert config.get_timeout_for("general-purpose") == 600
         assert config.get_timeout_for("bash") == 600
         assert config.get_timeout_for("unknown-agent") == 600
+        assert config.get_max_turns_for("general-purpose", 100) == 100
+        assert config.get_max_turns_for("bash", 60) == 60
 
     def test_returns_per_agent_override_when_set(self):
         config = SubagentsAppConfig(
             timeout_seconds=900,
-            agents={"bash": SubagentOverrideConfig(timeout_seconds=300)},
+            max_turns=120,
+            agents={"bash": SubagentOverrideConfig(timeout_seconds=300, max_turns=80)},
         )
         assert config.get_timeout_for("bash") == 300
+        assert config.get_max_turns_for("bash", 60) == 80
 
     def test_other_agents_still_use_global_default(self):
         config = SubagentsAppConfig(
             timeout_seconds=900,
-            agents={"bash": SubagentOverrideConfig(timeout_seconds=300)},
+            max_turns=140,
+            agents={"bash": SubagentOverrideConfig(timeout_seconds=300, max_turns=80)},
         )
         assert config.get_timeout_for("general-purpose") == 900
+        assert config.get_max_turns_for("general-purpose", 100) == 140
 
     def test_agent_with_none_override_falls_back_to_global(self):
         config = SubagentsAppConfig(
             timeout_seconds=900,
-            agents={"general-purpose": SubagentOverrideConfig(timeout_seconds=None)},
+            max_turns=150,
+            agents={"general-purpose": SubagentOverrideConfig(timeout_seconds=None, max_turns=None)},
         )
         assert config.get_timeout_for("general-purpose") == 900
+        assert config.get_max_turns_for("general-purpose", 100) == 150
 
     def test_multiple_per_agent_overrides(self):
         config = SubagentsAppConfig(
             timeout_seconds=900,
+            max_turns=120,
             agents={
-                "general-purpose": SubagentOverrideConfig(timeout_seconds=1800),
-                "bash": SubagentOverrideConfig(timeout_seconds=120),
+                "general-purpose": SubagentOverrideConfig(timeout_seconds=1800, max_turns=200),
+                "bash": SubagentOverrideConfig(timeout_seconds=120, max_turns=80),
             },
         )
         assert config.get_timeout_for("general-purpose") == 1800
         assert config.get_timeout_for("bash") == 120
+        assert config.get_max_turns_for("general-purpose", 100) == 200
+        assert config.get_max_turns_for("bash", 60) == 80
 
 
 # ---------------------------------------------------------------------------
@@ -139,54 +177,63 @@ class TestLoadSubagentsConfig:
         _reset_subagents_config()
 
     def test_load_global_timeout(self):
-        load_subagents_config_from_dict({"timeout_seconds": 300})
+        load_subagents_config_from_dict({"timeout_seconds": 300, "max_turns": 120})
         assert get_subagents_app_config().timeout_seconds == 300
+        assert get_subagents_app_config().max_turns == 120
 
     def test_load_with_per_agent_overrides(self):
         load_subagents_config_from_dict(
             {
                 "timeout_seconds": 900,
+                "max_turns": 120,
                 "agents": {
-                    "general-purpose": {"timeout_seconds": 1800},
-                    "bash": {"timeout_seconds": 60},
+                    "general-purpose": {"timeout_seconds": 1800, "max_turns": 200},
+                    "bash": {"timeout_seconds": 60, "max_turns": 80},
                 },
             }
         )
         cfg = get_subagents_app_config()
         assert cfg.get_timeout_for("general-purpose") == 1800
         assert cfg.get_timeout_for("bash") == 60
+        assert cfg.get_max_turns_for("general-purpose", 100) == 200
+        assert cfg.get_max_turns_for("bash", 60) == 80
 
     def test_load_partial_override(self):
         load_subagents_config_from_dict(
             {
                 "timeout_seconds": 600,
-                "agents": {"bash": {"timeout_seconds": 120}},
+                "agents": {"bash": {"timeout_seconds": 120, "max_turns": 70}},
             }
         )
         cfg = get_subagents_app_config()
         assert cfg.get_timeout_for("general-purpose") == 600
         assert cfg.get_timeout_for("bash") == 120
+        assert cfg.get_max_turns_for("general-purpose", 100) == 100
+        assert cfg.get_max_turns_for("bash", 60) == 70
 
     def test_load_empty_dict_uses_defaults(self):
         load_subagents_config_from_dict({})
         cfg = get_subagents_app_config()
         assert cfg.timeout_seconds == 900
+        assert cfg.max_turns is None
         assert cfg.agents == {}
 
     def test_load_replaces_previous_config(self):
-        load_subagents_config_from_dict({"timeout_seconds": 100})
+        load_subagents_config_from_dict({"timeout_seconds": 100, "max_turns": 90})
         assert get_subagents_app_config().timeout_seconds == 100
+        assert get_subagents_app_config().max_turns == 90
 
-        load_subagents_config_from_dict({"timeout_seconds": 200})
+        load_subagents_config_from_dict({"timeout_seconds": 200, "max_turns": 110})
         assert get_subagents_app_config().timeout_seconds == 200
+        assert get_subagents_app_config().max_turns == 110
 
     def test_singleton_returns_same_instance_between_calls(self):
-        load_subagents_config_from_dict({"timeout_seconds": 777})
+        load_subagents_config_from_dict({"timeout_seconds": 777, "max_turns": 123})
         assert get_subagents_app_config() is get_subagents_app_config()
 
 
 # ---------------------------------------------------------------------------
-# registry.get_subagent_config – timeout override applied
+# registry.get_subagent_config – runtime overrides applied
 # ---------------------------------------------------------------------------
 
 
@@ -211,25 +258,29 @@ class TestRegistryGetSubagentConfig:
         _reset_subagents_config(timeout_seconds=900)
         config = get_subagent_config("general-purpose")
         assert config.timeout_seconds == 900
+        assert config.max_turns == 100
 
     def test_global_timeout_override_applied(self):
         from deerflow.subagents.registry import get_subagent_config
 
-        _reset_subagents_config(timeout_seconds=1800)
+        _reset_subagents_config(timeout_seconds=1800, max_turns=140)
         config = get_subagent_config("general-purpose")
         assert config.timeout_seconds == 1800
+        assert config.max_turns == 140
 
-    def test_per_agent_timeout_override_applied(self):
+    def test_per_agent_runtime_override_applied(self):
         from deerflow.subagents.registry import get_subagent_config
 
         load_subagents_config_from_dict(
             {
                 "timeout_seconds": 900,
-                "agents": {"bash": {"timeout_seconds": 120}},
+                "max_turns": 120,
+                "agents": {"bash": {"timeout_seconds": 120, "max_turns": 80}},
             }
         )
         bash_config = get_subagent_config("bash")
         assert bash_config.timeout_seconds == 120
+        assert bash_config.max_turns == 80
 
     def test_per_agent_override_does_not_affect_other_agents(self):
         from deerflow.subagents.registry import get_subagent_config
@@ -237,11 +288,13 @@ class TestRegistryGetSubagentConfig:
         load_subagents_config_from_dict(
             {
                 "timeout_seconds": 900,
-                "agents": {"bash": {"timeout_seconds": 120}},
+                "max_turns": 120,
+                "agents": {"bash": {"timeout_seconds": 120, "max_turns": 80}},
             }
         )
         gp_config = get_subagent_config("general-purpose")
         assert gp_config.timeout_seconds == 900
+        assert gp_config.max_turns == 120
 
     def test_builtin_config_object_is_not_mutated(self):
         """Registry must return a new object, leaving the builtin default intact."""
@@ -249,24 +302,27 @@ class TestRegistryGetSubagentConfig:
         from deerflow.subagents.registry import get_subagent_config
 
         original_timeout = BUILTIN_SUBAGENTS["bash"].timeout_seconds
-        load_subagents_config_from_dict({"timeout_seconds": 42})
+        original_max_turns = BUILTIN_SUBAGENTS["bash"].max_turns
+        load_subagents_config_from_dict({"timeout_seconds": 42, "max_turns": 88})
 
         returned = get_subagent_config("bash")
         assert returned.timeout_seconds == 42
+        assert returned.max_turns == 88
         assert BUILTIN_SUBAGENTS["bash"].timeout_seconds == original_timeout
+        assert BUILTIN_SUBAGENTS["bash"].max_turns == original_max_turns
 
     def test_config_preserves_other_fields(self):
-        """Applying timeout override must not change other SubagentConfig fields."""
+        """Applying runtime overrides must not change other SubagentConfig fields."""
         from deerflow.subagents.builtins import BUILTIN_SUBAGENTS
         from deerflow.subagents.registry import get_subagent_config
 
-        _reset_subagents_config(timeout_seconds=300)
+        _reset_subagents_config(timeout_seconds=300, max_turns=140)
         original = BUILTIN_SUBAGENTS["general-purpose"]
         overridden = get_subagent_config("general-purpose")
 
         assert overridden.name == original.name
         assert overridden.description == original.description
-        assert overridden.max_turns == original.max_turns
+        assert overridden.max_turns == 140
         assert overridden.model == original.model
         assert overridden.tools == original.tools
         assert overridden.disallowed_tools == original.disallowed_tools
@@ -291,9 +347,10 @@ class TestRegistryListSubagents:
     def test_all_returned_configs_get_global_override(self):
         from deerflow.subagents.registry import list_subagents
 
-        _reset_subagents_config(timeout_seconds=123)
+        _reset_subagents_config(timeout_seconds=123, max_turns=77)
         for cfg in list_subagents():
             assert cfg.timeout_seconds == 123, f"{cfg.name} has wrong timeout"
+            assert cfg.max_turns == 77, f"{cfg.name} has wrong max_turns"
 
     def test_per_agent_overrides_reflected_in_list(self):
         from deerflow.subagents.registry import list_subagents
@@ -301,15 +358,18 @@ class TestRegistryListSubagents:
         load_subagents_config_from_dict(
             {
                 "timeout_seconds": 900,
+                "max_turns": 120,
                 "agents": {
-                    "general-purpose": {"timeout_seconds": 1800},
-                    "bash": {"timeout_seconds": 60},
+                    "general-purpose": {"timeout_seconds": 1800, "max_turns": 200},
+                    "bash": {"timeout_seconds": 60, "max_turns": 80},
                 },
             }
         )
         by_name = {cfg.name: cfg for cfg in list_subagents()}
         assert by_name["general-purpose"].timeout_seconds == 1800
         assert by_name["bash"].timeout_seconds == 60
+        assert by_name["general-purpose"].max_turns == 200
+        assert by_name["bash"].max_turns == 80
 
 
 # ---------------------------------------------------------------------------