Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

fix(research): bound progress and persist completion (#6904)

LearningCircuit3da499bf8079
diff --git a/changelog.d/+research-progress-bounds.bugfix.md b/changelog.d/+research-progress-bounds.bugfix.md
new file mode 100644
index 0000000000..cb224b4b95
--- /dev/null
+++ b/changelog.d/+research-progress-bounds.bugfix.md
@@ -0,0 +1 @@
+Keep research progress between 0% and 100%, and reach 100% only when a run completes. The source-based strategy no longer reports 125% (2 iterations) or 137% (3 iterations) after its last iteration, and a strategy finishing its search no longer shows 100% while the answer is still being generated. A completed run is saved with 100% progress, so status polling and realtime updates both end at 100%.
diff --git a/src/local_deep_research/advanced_search_system/strategies/focused_iteration_strategy.py b/src/local_deep_research/advanced_search_system/strategies/focused_iteration_strategy.py
index d5daa2ea22..f4c53e4b2f 100644
--- a/src/local_deep_research/advanced_search_system/strategies/focused_iteration_strategy.py
+++ b/src/local_deep_research/advanced_search_system/strategies/focused_iteration_strategy.py
@@ -174,14 +174,17 @@ class FocusedIterationStrategy(BaseSearchStrategy):
for iteration in range(1, self.max_iterations + 1):
# Check cancellation before each iteration to avoid 30-50s lag between Stop click and actual halt.
self.check_termination(CHECK_CONTEXT_ITERATION_START)
- iteration_progress = 10 + (iteration - 1) * (
- 80 / self.max_iterations
- )
+ iteration_band = 80 / self.max_iterations
+ iteration_progress = 10 + (iteration - 1) * iteration_band
- # Show context-aware progress message for question generation
+ # Show context-aware progress message for question generation.
+ # Stay inside this iteration's band so a large
+ # max_iterations cannot push the last iteration past
+ # synthesis (90).
self._emit_question_generation_progress(
iteration=iteration,
- progress_percent=iteration_progress + 2,
+ progress_percent=iteration_progress
+ + min(2, iteration_band / 2),
source_count=len(self.all_search_results)
if iteration > 1
else 0,
diff --git a/src/local_deep_research/advanced_search_system/strategies/source_based_strategy.py b/src/local_deep_research/advanced_search_system/strategies/source_based_strategy.py
index 4e95b839cd..e12724979e 100644
--- a/src/local_deep_research/advanced_search_system/strategies/source_based_strategy.py
+++ b/src/local_deep_research/advanced_search_system/strategies/source_based_strategy.py
@@ -467,7 +467,11 @@ class SourceBasedSearchStrategy(BaseSearchStrategy):
)
self._update_progress(
f"Filtered from {len(accumulated_search_results_across_all_iterations)} to {len(final_filtered_results)} results",
- iteration_progress_base + 85,
+ # Fixed point between final_filtering (80) and
+ # synthesis (90). This runs after the iteration loop;
+ # adding the last iteration's base here overshot 100
+ # (125% with 2 iterations, 136.7% with 3).
+ 85,
{
"phase": "filtering_complete",
"iteration": iteration,
diff --git a/src/local_deep_research/web/research_state.py b/src/local_deep_research/web/research_state.py
index 88857dbefc..5fe40d7508 100644
--- a/src/local_deep_research/web/research_state.py
+++ b/src/local_deep_research/web/research_state.py
@@ -270,20 +270,12 @@ def append_research_log(research_id, log_entry):
def update_progress_if_higher(research_id, new_progress):
- """Atomically update progress only if *new_progress* exceeds current.
+ """Atomically update bounded progress only if it exceeds current.
Returns the resulting progress value, or ``None`` if the research is
not active.
"""
- with _lock:
- entry = _active_research.get(research_id)
- if entry is None:
- return None
- current = entry.get("progress", 0)
- if new_progress is not None and new_progress > current:
- entry["progress"] = new_progress
- return new_progress
- return current
+ return update_progress_and_check_active(research_id, new_progress)[0]
def remove_active_research(research_id):
@@ -375,7 +367,7 @@ def is_research_thread_alive(research_id):
def update_progress_and_check_active(research_id, new_progress):
- """Atomically update progress (if higher) and check if research is active.
+ """Atomically bound progress to 0..100 and advance it monotonically.
Returns ``(progress_value, is_active)`` where *progress_value* is the
resulting progress (or ``None`` if not active) and *is_active* indicates
@@ -385,10 +377,13 @@ def update_progress_and_check_active(research_id, new_progress):
entry = _active_research.get(research_id)
if entry is None:
return (None, False)
- current = entry.get("progress", 0)
- if new_progress is not None and new_progress > current:
- entry["progress"] = new_progress
- return (new_progress, True)
+ # A strategy can overshoot its phase allocation. Clamp before the
+ # monotonic comparison: otherwise an overshoot becomes a permanent
+ # floor and even the worker's final 100% update cannot correct it.
+ current = min(100, max(0, entry.get("progress", 0)))
+ if new_progress is not None:
+ current = max(current, min(100, max(0, new_progress)))
+ entry["progress"] = current
return (current, True)
diff --git a/src/local_deep_research/web/services/research_service.py b/src/local_deep_research/web/services/research_service.py
index c7ecc8a74a..6edd3e24bb 100644
--- a/src/local_deep_research/web/services/research_service.py
+++ b/src/local_deep_research/web/services/research_service.py
@@ -128,6 +128,20 @@ def clamp_user_max_concurrent(raw_value) -> int:
_DETAILED_SEARCH_PROGRESS_CAP = 8 # Search/output phases capped here
_DETAILED_REPORT_PROGRESS_START = 10 # Report generation starts here
_DETAILED_REPORT_PROGRESS_END = 100 # Report generation ends here
+# Quick mode: the search strategy reports up to here, then the answer is
+# generated in the 85-95% band (see progress_callback).
+_QUICK_OUTPUT_PROGRESS_START = 85
+# 100% is reserved for the run's own successful completion. The frontend
+# treats ``progress >= 100`` as "research finished" (chat.js, progress.js),
+# so every in-progress value is capped below it -- a strategy that reports
+# its own completion at 100%, or an overshooting phase mapping, must not
+# end the run in the UI while the answer is still being generated.
+_IN_PROGRESS_CAP = 99
+# Metadata flag carried only by run_research_process's final
+# ``phase="complete"`` emit. It is the explicit completion signal: strategies
+# also emit ``phase="complete"`` when their analyze_topic returns, which is
+# mid-run (quick: before answer generation; detailed: once per subsection).
+_RUN_COMPLETE_FLAG = "_run_complete"
# Phases that belong to the report-generation stage. "report_generation" is
# emitted in this file; the other four are emitted by report_generator.py. If
# you add or rename a phase, update both this set and the emitter.
@@ -191,16 +205,18 @@ def _chat_step_decision(
- persist: True iff add_progress_step should be called for this event.
- suppress_emit: True iff the caller should null the socket payload
so the emit is dropped. Only suppressed when this is a non-final
- repeat — final phases (complete/error/report_complete) always
- emit so the client completion handler fires.
+ repeat — final events (error/report_complete, or the run's
+ explicit completion) always emit so the client completion
+ handler fires.
Args:
phase: the phase tag from this event (e.g. "search", "observation")
last_step_phase: phase tag of the previously persisted chat step
(None until the first persist of this research).
- is_final: True if this is a "final" phase event the client must
- see to fire its completion handler (complete | error |
- report_complete | progress==100).
+ is_final: True if this is a "final" event the client must see to
+ fire its completion handler (error | report_complete | the
+ run's own completion emit, flagged with _RUN_COMPLETE_FLAG).
+ A progress value alone never makes an event final.
"""
if phase not in _STEP_PHASES:
# Not a chat-step phase at all (e.g. "complete"). Persist no,
@@ -1346,11 +1362,18 @@ def run_research_process(research_id, query, mode, **kwargs):
"iteration"
]
+ # Only run_research_process's own final emit carries this flag;
+ # pop it so it never reaches the socket payload or chat step.
+ run_complete = metadata.pop(_RUN_COMPLETE_FLAG, False) is True
+
# Adjust progress based on research mode
adjusted_progress = progress_percent
phase = metadata.get("phase", "")
- if mode == "detailed":
+ if run_complete:
+ # The run's own completion emit is never remapped or capped.
+ pass
+ elif mode == "detailed":
# Report phases pass through (already mapped by wrapper).
# All other phases — including "complete" emitted by each
# strategy when its analyze_topic finishes (report
@@ -1373,9 +1396,32 @@ def run_research_process(research_id, query, mode, **kwargs):
):
# For quick mode, scale output_generation to 85-95% range
if progress_percent > 0:
- adjusted_progress = 85 + (progress_percent / 100) * 10
+ adjusted_progress = (
+ _QUICK_OUTPUT_PROGRESS_START
+ + (progress_percent / 100) * 10
+ )
else:
- adjusted_progress = 85
+ adjusted_progress = _QUICK_OUTPUT_PROGRESS_START
+ elif (
+ mode == "quick"
+ and phase == "complete"
+ and progress_percent is not None
+ ):
+ # The strategy finished searching; answer generation (the
+ # 85-95% band) is still ahead.
+ adjusted_progress = min(
+ _QUICK_OUTPUT_PROGRESS_START, progress_percent
+ )
+
+ # Reserve 100 for the run's completion signal. Written as a
+ # comparison (not min()) so a NaN passes through unchanged and
+ # is rejected by the registry instead of becoming 99.
+ if (
+ not run_complete
+ and adjusted_progress is not None
+ and adjusted_progress > _IN_PROGRESS_CAP
+ ):
+ adjusted_progress = _IN_PROGRESS_CAP
# Atomically update progress and check if research is still active
if adjusted_progress is not None:
@@ -1401,16 +1447,14 @@ def run_research_process(research_id, query, mode, **kwargs):
f"Cannot queue progress update for research {research_id} - no username available"
)
- # Determine socket emit throttling
+ # Determine socket emit throttling. Completion is the
+ # explicit run_complete signal -- never a progress value
+ # (a clamped overshoot used to reach 100 mid-run) and never
+ # a bare phase="complete" (strategies emit that mid-run).
phase = metadata.get("phase", "")
- is_final = (
- phase
- in (
- "complete",
- "error",
- "report_complete",
- )
- or adjusted_progress == 100
+ is_final = run_complete or phase in (
+ "error",
+ "report_complete",
)
should_emit = is_final
@@ -2284,6 +2328,7 @@ def run_research_process(research_id, query, mode, **kwargs):
)
research.status = ResearchStatus.COMPLETED
+ research.progress = 100
research.completed_at = completed_at
research.duration_seconds = duration_seconds
# report_content was already saved above via the report
@@ -2412,7 +2457,7 @@ def run_research_process(research_id, query, mode, **kwargs):
progress_callback(
"Research completed successfully",
100,
- {"phase": "complete"},
+ {"phase": "complete", _RUN_COMPLETE_FLAG: True},
)
# Clean up resources
@@ -2610,6 +2655,7 @@ def run_research_process(research_id, query, mode, **kwargs):
)
research.status = ResearchStatus.COMPLETED
+ research.progress = 100
research.completed_at = completed_at
research.duration_seconds = duration_seconds
# report_content was already saved above via the report storage
@@ -2713,7 +2759,7 @@ def run_research_process(research_id, query, mode, **kwargs):
progress_callback(
"Research completed successfully",
100,
- {"phase": "complete"},
+ {"phase": "complete", _RUN_COMPLETE_FLAG: True},
)
# Clean up resources
diff --git a/tests/strategies/test_multi_iteration_progress.py b/tests/strategies/test_multi_iteration_progress.py
new file mode 100644
index 0000000000..cc008a8778
--- /dev/null
+++ b/tests/strategies/test_multi_iteration_progress.py
@@ -0,0 +1,279 @@
+"""Multi-iteration runs report monotonic progress that reaches 100 only at the end.
+
+Issue #6062: source_based_strategy emitted ``iteration_progress_base + 85``
+for ``filtering_complete`` after the iteration loop, i.e. 125% with 2
+iterations and 136.7% with 3. The registry clamp then pinned the bar at
+exactly 100 before synthesis, and ``progress == 100`` made every later
+callback "final" (throttle and chat repeat-suppression bypassed) while the
+answer was still being generated.
+
+These tests drive the REAL strategy with the strategy fixtures' mocked LLM
+and search, first on its own and then through the REAL progress_callback
+closure of run_research_process with the real research_state registry.
+"""
+
+import pytest
+
+from local_deep_research.search_system_factory import create_strategy
+from local_deep_research.web import research_state
+from local_deep_research.web.services import research_service
+from tests.web.services.test_research_service_progress_integration import (
+ captured_progress_callback,
+)
+
+
+def _strategy(name, iterations, llm, search, snapshot):
+ snapshot = dict(snapshot)
+ snapshot["search.iterations"] = {"value": iterations, "type": "int"}
+ return create_strategy(
+ strategy_name=name,
+ model=llm,
+ search=search,
+ settings_snapshot=snapshot,
+ max_iterations=iterations,
+ )
+
+
+def _assert_monotonic_and_bounded(values, upper):
+ assert values, "no progress values were emitted"
+ for value in values:
+ assert 0 <= value <= upper, values
+ for earlier, later in zip(values, values[1:]):
+ assert later >= earlier, f"progress went backwards: {values}"
+
+
[email protected]("iterations", [2, 3])
[email protected]("name", ["source-based", "focused-iteration"])
+def test_strategy_progress_is_monotonic_and_within_bounds(
+ name,
+ iterations,
+ strategy_mock_llm,
+ strategy_mock_search,
+ strategy_settings_snapshot,
+):
+ strategy = _strategy(
+ name,
+ iterations,
+ strategy_mock_llm,
+ strategy_mock_search,
+ strategy_settings_snapshot,
+ )
+ events = []
+ strategy.set_progress_callback(
+ lambda _message, progress, metadata: events.append(
+ (progress, dict(metadata or {}))
+ )
+ )
+
+ strategy.analyze_topic("What is artificial intelligence?")
+
+ phases = [metadata.get("phase") for _, metadata in events]
+ # Every iteration reported its question-generation step, inside the
+ # band before synthesis (90).
+ iteration_steps = [
+ progress
+ for progress, metadata in events
+ if metadata.get("phase") == "question_generation"
+ ]
+ assert len(iteration_steps) >= iterations, events
+ assert all(progress < 90 for progress in iteration_steps), events
+ if name == "source-based":
+ # The overshooting emitter must actually have run.
+ assert "filtering_complete" in phases, phases
+ assert "synthesis" in phases, phases
+ values = [
+ progress
+ for progress, metadata in events
+ if progress is not None and metadata.get("phase") != "error"
+ ]
+ _assert_monotonic_and_bounded(values, 100)
+ # Everything before synthesis stays at or below the synthesis milestone.
+ if "synthesis" in phases:
+ synthesis_at = phases.index("synthesis")
+ assert all(
+ progress <= 90
+ for progress, _ in events[:synthesis_at]
+ if progress is not None
+ ), events
+
+
[email protected]("iterations", [2, 3])
+def test_quick_run_reaches_100_and_is_final_only_on_completion(
+ iterations,
+ strategy_mock_llm,
+ strategy_mock_search,
+ strategy_settings_snapshot,
+):
+ """Real strategy -> real closure -> real registry, chat session on.
+
+ ``_chat_step_decision`` receives the closure's ``is_final`` for every
+ active event, so wrapping it records exactly what the throttle and the
+ chat repeat-suppression saw.
+ """
+ from unittest.mock import patch
+
+ research_id = f"multi-iteration-progress-{iterations}"
+ decisions = []
+ real_decision = research_service._chat_step_decision
+
+ def record_decision(phase, last_step_phase, is_final):
+ decisions.append((phase, is_final))
+ return real_decision(phase, last_step_phase, is_final)
+
+ extras = {}
+ with captured_progress_callback(
+ "quick",
+ run_kwargs={
+ "research_id": research_id,
+ "chat_session_id": f"sess-{research_id}",
+ },
+ extras=extras,
+ real_registry=True,
+ ) as (cb, _, update_calls):
+ research_state.set_active_research(
+ research_id, {"progress": 0, "status": "in_progress"}
+ )
+ try:
+ update_calls.clear()
+ with patch.object(
+ research_service,
+ "_chat_step_decision",
+ side_effect=record_decision,
+ ):
+ strategy = _strategy(
+ "source-based",
+ iterations,
+ strategy_mock_llm,
+ strategy_mock_search,
+ strategy_settings_snapshot,
+ )
+ strategy.set_progress_callback(cb)
+ strategy.analyze_topic("What is artificial intelligence?")
+
+ # run_research_process's quick-mode tail, in order.
+ cb(
+ "Search complete, preparing to generate summary...",
+ 85,
+ {"phase": "output_generation"},
+ )
+ cb(
+ "Generating clean summary from research data...",
+ 90,
+ {"phase": "output_generation"},
+ )
+ cb(
+ "Saving research report to database...",
+ 95,
+ {"phase": "report_complete"},
+ )
+
+ in_progress = [stored for _, _, stored in update_calls]
+ _assert_monotonic_and_bounded(in_progress, 99)
+ assert max(in_progress) < 100, in_progress
+ # The only final event so far is report_complete itself.
+ assert [p for p, final in decisions if final] == [
+ "report_complete"
+ ], decisions
+ for _, _, payload in (
+ c.args for c in extras["socketio"].call_args_list
+ ):
+ assert payload["progress"] < 100, payload
+
+ cb(
+ "Research completed successfully",
+ 100,
+ {
+ "phase": "complete",
+ research_service._RUN_COMPLETE_FLAG: True,
+ },
+ )
+ finally:
+ research_state.cleanup_research(research_id)
+
+ assert update_calls[-1][2] == 100
+ assert decisions[-1] == ("complete", True)
+ final_payload = extras["socketio"].call_args_list[-1].args[2]
+ assert final_payload["progress"] == 100
+ assert research_service._RUN_COMPLETE_FLAG not in final_payload
+
+
+def test_strategy_complete_at_100_does_not_finish_a_quick_run():
+ """The default langgraph strategy ends analyze_topic with
+ phase="complete" at 100, before the answer is generated."""
+ research_id = "strategy-complete-quick"
+ with captured_progress_callback(
+ "quick", run_kwargs={"research_id": research_id}, real_registry=True
+ ) as (cb, state, _):
+ research_state.set_active_research(
+ research_id, {"progress": 0, "status": "in_progress"}
+ )
+ try:
+ cb("Synthesizing", 90, {"phase": "synthesis"})
+ cb("Research complete", 100, {"phase": "complete"})
+ assert state[0] == 90
+ cb("Generating", 90, {"phase": "output_generation"})
+ assert 90 < state[0] < 100
+ cb("Strategy error", 100, {"phase": "error"})
+ assert state[0] == research_service._IN_PROGRESS_CAP
+ finally:
+ research_state.cleanup_research(research_id)
+
+
+class _BareCompleteStrategy:
+ """Minimal strategy: reports progress, then a bare phase="complete" at
+ 100 mid-run (as the langgraph strategy does before the answer exists)."""
+
+ def __init__(self, cb):
+ self.cb = cb
+
+ def analyze_topic(self):
+ self.cb("Synthesizing", 90, {"phase": "synthesis"})
+ self.cb("Research complete", 100, {"phase": "complete"})
+
+
[email protected]("chat", [False, True])
+def test_strategy_bare_complete_mid_run_is_not_final(chat):
+ """A strategy's own phase="complete" at 100 is not the run's end: the
+ emit throttle still applies and _chat_step_decision sees is_final=False.
+ (Fails if ``phase == "complete"`` is added back to is_final.)"""
+ from unittest.mock import patch
+
+ research_id = f"bare-complete-{chat}"
+ decisions = []
+ real_decision = research_service._chat_step_decision
+
+ def record_decision(phase, last_step_phase, is_final):
+ decisions.append((phase, is_final))
+ return real_decision(phase, last_step_phase, is_final)
+
+ run_kwargs = {"research_id": research_id}
+ if chat:
+ run_kwargs["chat_session_id"] = f"sess-{research_id}"
+ extras = {}
+ with captured_progress_callback(
+ "quick", run_kwargs=run_kwargs, extras=extras, real_registry=True
+ ) as (cb, state, _):
+ research_state.set_active_research(
+ research_id, {"progress": 0, "status": "in_progress"}
+ )
+ try:
+ with patch.object(
+ research_service,
+ "_chat_step_decision",
+ side_effect=record_decision,
+ ):
+ _BareCompleteStrategy(cb).analyze_topic()
+ assert state[0] < 100
+ if chat:
+ assert ("complete", True) not in decisions, decisions
+ assert ("complete", False) in decisions, decisions
+ else:
+ # Back-to-back events: the second is inside the throttle
+ # window, so only the first (synthesis) reaches the socket.
+ phases = [
+ c.args[2]["phase"]
+ for c in extras["socketio"].call_args_list
+ ]
+ assert phases == ["synthesis"], phases
+ finally:
+ research_state.cleanup_research(research_id)
diff --git a/tests/web/services/test_research_service_execution.py b/tests/web/services/test_research_service_execution.py
index 0b754827ee..23c7a0a8e3 100644
--- a/tests/web/services/test_research_service_execution.py
+++ b/tests/web/services/test_research_service_execution.py
@@ -19,7 +19,9 @@ from local_deep_research.settings.manager import SnapshotSettingsContext
from local_deep_research.web.services.research_service import (
_DETAILED_REPORT_PROGRESS_END,
_DETAILED_SEARCH_PROGRESS_CAP,
+ _IN_PROGRESS_CAP,
_REPORT_PHASES,
+ _RUN_COMPLETE_FLAG,
)
from tests.web.services.helpers import (
MODULE,
@@ -236,12 +238,14 @@ class TestDetailedModeSearchCap:
"at 10"
)
- def test_legitimate_final_complete_uses_report_complete_phase(self):
- """The legitimate end-of-research 100 emit uses phase='report_complete'.
+ def test_only_the_flagged_run_completion_reaches_100(self):
+ """report_complete ends the report range but not the run.
- Confirms both that the constant membership is what production
- code relies on, AND that driving the real closure with that
- phase actually reaches 100 — not just a constants check.
+ Citation formatting and the database save still follow it, so it is
+ held just below 100. Only run_research_process's own completion
+ emit, flagged with _RUN_COMPLETE_FLAG, reaches 100 -- in detailed
+ mode too, where an unflagged phase="complete" is capped at the
+ search cap.
"""
assert "report_complete" in _REPORT_PHASES
assert "complete" not in _REPORT_PHASES
@@ -251,7 +255,13 @@ class TestDetailedModeSearchCap:
_DETAILED_REPORT_PROGRESS_END,
{"phase": "report_complete"},
)
- assert state[0] == _DETAILED_REPORT_PROGRESS_END
+ assert state[0] == _IN_PROGRESS_CAP
+ cb(
+ "Research completed successfully",
+ 100,
+ {"phase": "complete", _RUN_COMPLETE_FLAG: True},
+ )
+ assert state[0] == 100
class TestTerminationHandling:
diff --git a/tests/web/services/test_research_service_progress_integration.py b/tests/web/services/test_research_service_progress_integration.py
index 1b3f17377b..a082c0deb4 100644
--- a/tests/web/services/test_research_service_progress_integration.py
+++ b/tests/web/services/test_research_service_progress_integration.py
@@ -53,7 +53,9 @@ def _noop_db_session(*_, **__):
@contextmanager
-def captured_progress_callback(mode, run_kwargs=None, extras=None):
+def captured_progress_callback(
+ mode, run_kwargs=None, extras=None, real_registry=False
+):
"""Yield (callback, progress_state, update_calls) with patches active.
progress_state[0] is the value globals.update_progress_and_check_active
@@ -67,6 +69,11 @@ def captured_progress_callback(mode, run_kwargs=None, extras=None):
``extras``, when given a dict, is populated with the ``socketio``
service mock and the patched ``chat_service_cls`` so tests can assert
on emits and persisted steps.
+
+ ``real_registry=True`` routes progress through the production
+ ``research_state.update_progress_and_check_active`` (clamp + monotonic
+ guard) instead of the stateful fake; the caller must register the
+ research with ``research_state.set_active_research`` first.
"""
from local_deep_research.exceptions import ResearchTerminatedException
from local_deep_research.web.services.research_service import (
@@ -87,7 +94,16 @@ def captured_progress_callback(mode, run_kwargs=None, extras=None):
progress_state = [0]
update_calls = []
+ from local_deep_research.web import research_state
+
+ real_update = research_state.update_progress_and_check_active
+
def fake_monotonic_update(rid, new_progress):
+ if real_registry:
+ stored, active = real_update(rid, new_progress)
+ progress_state[0] = stored
+ update_calls.append((rid, new_progress, stored))
+ return (stored, active)
if new_progress is not None and new_progress > progress_state[0]:
progress_state[0] = new_progress
update_calls.append((rid, new_progress, progress_state[0]))
@@ -251,7 +267,11 @@ class TestRunResearchProcessProgressCallbackIntegration:
)
def test_report_phase_sequence_climbs_through_closure(self):
- """A normal report-phase emission sequence drives the bar 10 → 100."""
+ """A normal report-phase emission sequence drives the bar 10 → 99.
+
+ 100 is reserved for the run's flagged completion emit, which comes
+ after citation formatting and the database save.
+ """
with captured_progress_callback("detailed") as (
cb,
progress_state,
@@ -262,7 +282,7 @@ class TestRunResearchProcessProgressCallbackIntegration:
cb("section 2", 60, {"phase": "report_section_research"})
cb("formatting", 91, {"phase": "report_formatting"})
cb("complete", 100, {"phase": "report_complete"})
- assert progress_state[0] == 100
+ assert progress_state[0] == research_service._IN_PROGRESS_CAP
def test_search_phase_capped_through_closure(self):
"""Search-phase emissions are capped at the configured search cap."""
diff --git a/tests/web/test_research_progress_bounds.py b/tests/web/test_research_progress_bounds.py
new file mode 100644
index 0000000000..152a44cf2f
--- /dev/null
+++ b/tests/web/test_research_progress_bounds.py
@@ -0,0 +1,52 @@
+"""Progress updates stay usable by the worker, queue and HTTP status readers."""
+
+import pytest
+
+from local_deep_research.web import research_state
+
+
+ "update",
+ [
+ research_state.update_progress_if_higher,
+ research_state.update_progress_and_check_active,
+ ],
+)
+def test_progress_is_bounded_monotonic_and_does_not_change_status(update):
+ research_id = "progress-bounds-test"
+ research_state.set_active_research(
+ research_id, {"progress": 0, "status": "in_progress"}
+ )
+ try:
+ for value, expected in [
+ (-10, 0),
+ (42.5, 42.5),
+ (12, 42.5),
+ (float("nan"), 42.5),
+ (136.66666666666666, 100),
+ (100, 100),
+ (None, 100),
+ ]:
+ result = update(research_id, value)
+ assert result == expected or result == (expected, True)
+ snapshot = research_state.get_active_research_snapshot(research_id)
+ assert snapshot["progress"] == expected
+ assert snapshot["status"] == "in_progress"
+ finally:
+ research_state.cleanup_research(research_id)
+
+
[email protected]("stored,expected", [(-30, 50), (136.7, 100)])
+def test_an_existing_out_of_range_value_cannot_poison_later_updates(
+ stored, expected
+):
+ research_id = "previous-progress-bounds-test"
+ research_state.set_active_research(
+ research_id, {"progress": stored, "status": "in_progress"}
+ )
+ try:
+ assert research_state.update_progress_and_check_active(
+ research_id, 50
+ ) == (expected, True)
+ finally:
+ research_state.cleanup_research(research_id)
diff --git a/tests/web/test_research_socketio_delivery_integration.py b/tests/web/test_research_socketio_delivery_integration.py
index 445fb1a23a..43a46fe7b3 100644
--- a/tests/web/test_research_socketio_delivery_integration.py
+++ b/tests/web/test_research_socketio_delivery_integration.py
@@ -233,13 +233,24 @@ def test_research_worker_delivers_completion_over_real_socketio(
event_name, payload = completion
assert event_name == f"research_progress_{research_id}"
assert payload["message"] == "Research completed successfully", seen
- # This is a transport-wiring test. Exact progress normalization is
- # a separate research-service contract; phase + message + the HTTP
- # terminal state below establish that this is the terminal frame.
- assert isinstance(payload.get("progress"), (int, float)), seen
+ assert payload["progress"] == 100, seen
+ progress_values = [
+ observed["progress"]
+ for name, observed in seen
+ if name == event_name
+ and isinstance(observed, dict)
+ and observed.get("progress") is not None
+ ]
+ # Monotonic, and 100 only on the terminal frame: an earlier 100
+ # would end the run in the UI (chat.js treats >= 100 as done).
+ assert progress_values == sorted(progress_values), seen
+ assert all(0 <= value < 100 for value in progress_values[:-1]), seen
status = _poll_until_terminal(client, research_id)
assert status["status"] == "completed", status
+ # The HTTP status handler reads ResearchHistory from SQLCipher,
+ # independently of the in-memory value delivered over the socket.
+ assert status["progress"] == 100, status
# The production cleanup sleeps briefly in test mode, then removes
# the room. Waiting for that proves the worker got past the emit and
diff --git a/tests/web/test_research_state_registry.py b/tests/web/test_research_state_registry.py
index fc191da5ca..2251bf8442 100644
--- a/tests/web/test_research_state_registry.py
+++ b/tests/web/test_research_state_registry.py
@@ -1422,7 +1422,8 @@ def test_concurrent_log_appends_and_progress_updates_do_not_race(
research_id, {"w": index, "s": step}
)
research_state.update_progress_if_higher(
- research_id, index * per_writer + step
+ research_id,
+ (index * per_writer + step) * 100 / (writers * per_writer),
)
threads = [
@@ -1441,7 +1442,7 @@ def test_concurrent_log_appends_and_progress_updates_do_not_race(
)
assert len({(entry["w"], entry["s"]) for entry in log}) == len(log)
assert research_state.get_research_field(research_id, "progress") == (
- (writers - 1) * per_writer + per_writer - 1
+ (writers * per_writer - 1) * 100 / (writers * per_writer)
)