PlantAI-dev/docs/superpowers/plans/2026-07-10-reference-bundle-download-state.md

Reference Bundle Download State Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Prevent PPI/KaKs reference bundle downloads from being marked failed while they are still running, expose download progress, and resume Ortholog/PPI/KaKs after a true successful download.

Architecture: Keep the existing asynchronous /api/reference-bundle/download task model. Replace the stale timeout failure path with a non-terminal running status, persist progress on the task, and let the frontend poll until success or a real backend exception produces failed.

Tech Stack: FastAPI backend in apps/web/vue3/main.py, reference bundle download helpers in apps/web/pipeline_backend.py, Vue/Element Plus frontend in apps/web/vue3/index.html, pytest unit tests.

Global Constraints

• Do not change PPI/KaKs biological reference selection policy in this slice.
• Do not change At/soe fallback precedence in this slice.
• Do not redesign the Ka/Ks dependency dialog in this slice.
• A running download has no total wall-clock timeout. Network read/connect timeouts may still identify real transport failure.
• Success must clear stale fallback/action fields from persisted task status.

---

Task 1: Backend Task Status Semantics

Files:

• Modify: tests/unit/test_reference_bundle_task_status.py
• Modify: apps/web/vue3/main.py

Interfaces:

• Consumes: _apply_reference_bundle_stale_watchdog(task: Dict[str, Any])

• Produces: non-terminal running reference bundle task state with pending_seconds and progress

• Step 1: Replace the old timeout-failure test

Expected behavior: a long-running reference_bundle_download task remains running, records elapsed seconds, and persists status without action_required.

• Step 2: Run the test and confirm RED

Run: python -m pytest tests/unit/test_reference_bundle_task_status.py::test_reference_bundle_running_task_remains_running_after_elapsed_time -q

Expected: fail against current code because it still sets status == "failed".

• Step 3: Implement minimal backend status change

Update _apply_reference_bundle_stale_watchdog so it only refreshes pending_seconds and a running progress message; it must not set failed/fallback.

• Step 4: Run the test and confirm GREEN

Run: python -m pytest tests/unit/test_reference_bundle_task_status.py -q

Expected: all tests pass.

Task 2: Backend Download Progress

Files:

• Modify: tests/unit/test_pipeline_backend_execution_env.py
• Modify: apps/web/pipeline_backend.py
• Modify: apps/web/vue3/main.py

Interfaces:

• Consumes: _download_url_to_file(url, output_path, timeout_sec=300, attempts=3)

• Produces: optional progress callback events with phase, bytes, total, percentage

• Step 1: Add a progress callback unit test

Expected behavior: download_reference_annotation_bundle(..., progress_callback=callback) emits phases for selecting assembly, downloading, extracting, validating IDs, and completed.

• Step 2: Run callback test and confirm RED

Run: python -m pytest tests/unit/test_pipeline_backend_execution_env.py::test_reference_bundle_download_reports_progress_events -q

Expected: fail because the callback parameter does not exist.

• Step 3: Add optional progress callback

Add optional progress_callback: Optional[Callable[[dict[str, Any]], None]] = None to download_reference_annotation_bundle and _download_url_to_file. The default path remains backward compatible.

• Step 4: Persist progress in task status

In run_reference_bundle_download_task, provide a callback that updates tasks[task_id]["progress"] and persists the task.

• Step 5: Run callback and task status tests

Run: python -m pytest tests/unit/test_reference_bundle_task_status.py tests/unit/test_pipeline_backend_execution_env.py -k 'reference_bundle' -q

Expected: all selected tests pass.

Task 3: Frontend Polling And Progress Display

Files:

• Modify: apps/web/vue3/index.html

Interfaces:

• Consumes: /api/task/{task_id} response fields status, message, progress, result

• Produces: visible reference download progress and no fallback until terminal failed

• Step 1: Add reactive download state

Add a small referenceBundleDownloadState object with visible, taskId, speciesLabel, message, percentage, status.

• Step 2: Render progress in existing batch execution dialog

Add an Element Plus progress row near the existing batch progress. Avoid new modal UI.

• Step 3: Update polling

pollReferenceBundleDownloadTask should update progress on each poll, continue indefinitely until success/failed unless the user navigates away, and only throw on terminal failed/cancelled/revoked.

• Step 4: Clear progress on success and fallback only on real failure

On success, merge reference species, hide progress, and resume PPI/KaKs. On failed, preserve the existing fallback flow.

• Step 5: Validate frontend syntax

Run a script extraction parse check for apps/web/vue3/index.html.

Task 4: Verification

Files:

• Read-only validation against workspace/job_1783583324146_c5cb74/final/reference_bundle_tasks/2d425a54-3a4c-45a5-bd77-46765ea89c31.json

• Step 1: Syntax checks

Run: python -m py_compile apps/web/vue3/main.py apps/web/pipeline_backend.py

• Step 2: Unit tests

Run: python -m pytest tests/unit/test_reference_bundle_task_status.py tests/unit/test_pipeline_backend_execution_env.py -k 'reference_bundle' -q

• Step 3: Existing task status verification

Load the existing successful task JSON and confirm it has successful files. The status may still contain historical stale fields until a new task runs; new successful tasks must clear them.

• Step 4: Report remaining scope

State explicitly that At/soe fallback precedence and Ka/Ks dialog formatting remain separate follow-up tasks.