Merge pull request 'fix: count a run completed at the DONE transition, not after it (researchx#28)' (#29) from po/fix-cost-counter-race into main

Reviewed-on: #29

.ciagent/CHECKPOINT.json

@@ -1,8 +1,8 @@
 {
   "phase": 5,
-  "stage": "execute",
+  "stage": "complete",
   "milestone": "v0.2",
   "phase_role": "final",
   "attempts": 0,
-  "updated_at": "2026-09-27T15:05:00Z"
+  "updated_at": "2026-09-27T16:30:00Z"
 }

.ciagent/GRILL.md

@@ -215,4 +215,5 @@ The plan is sound with fixable gaps. The evidence base is unusually strong for a
 | G-010 | Meta | Pre-agreed contingency lever: if P2/P4 slip beyond one extension cycle, Deep Report (depth 3) defers to v0.3 and the MVP ships Rapid Answer end-to-end; pulling the lever requires owner sign-off at a gate. | 0.65 |
 
 ### Escalations
-- [G-009] Axis 2 — Owner ratification required at the P5 gate (D-018 halt): the v0.2 MVP demonstrates the **live core research loop only**; the remaining approved-prototype surfaces (Library, Settings persistence, Suggestions, Refine, graph/inbox previews, profile) remain mock-bound until v0.3+, and the live-mode gate demo requires a local backend + keys (or runs in mock mode) since D-019 forbids deploys. This redefines what "MVP done" looks like at the demo and must not be discovered by the owner at the gate — it must be ratified in advance. Engineering-side handling is bound in G-002/G-003; the ratification itself is unresolved until the owner records it.
+- [G-009] Axis 2 — Owner ratification required at the P5 gate (D-018 halt): the v0.2 MVP demonstrates the **live core research loop only**; the remaining approved-prototype surfaces (Library, Settings persistence, Suggestions, Refine, graph/inbox previews, profile) remain mock-bound until v0.3+, and the live-mode gate demo requires a local backend + keys (or runs in mock mode) since D-019 forbids deploys. This redefines what "MVP done" looks like at the demo and must not be discovered by the owner at the gate — it must be ratified in advance. Engineering-side handling is bound in G-002/G-003; the ratification itself is unresolved until the owner records it.
+  - **RESOLVED 2026-09-27: RATIFIED.** Owner approval recorded via /ci-run 'APPROVED' at the v0.2.5 gate (decision commit 4721c2a), following the owner-directed UAT staging at https://research.coreci.dev. Live-mode scope = core research loop only is the accepted MVP boundary; mock-bound surfaces move to v0.3+.

.ciagent/REQUIREMENTS.md

@@ -133,5 +133,5 @@
 | REQ-07, REQ-12, REQ-13..24 (probing, engine, trust) | v0.2 | P2 | complete (v0.2.2) |
 | REQ-25, REQ-26, REQ-33 (API, client, tooling) | v0.2 | P3 | complete (v0.2.3) |
 | REQ-17, REQ-32, REQ-34 (adversarial, E2E, round-trip) | v0.2 | P4 | complete (v0.2.4) |
-| All REQ-01..34 (milestone gate) | v0.2 | P5 | complete (v0.2.5 — all requirements covered; owner gate pending per D-018) |
+| All REQ-01..34 (milestone gate) | v0.2 | P5 | complete (v0.2.5 — **owner approval recorded 2026-09-27**, G-009 ratified; milestone merged to main) |
 | REQ-35..51 | v2 backlog (post-MVP milestones) | — | pending |

.ciagent/ROADMAP.md

@@ -75,7 +75,7 @@ prototype release is **v0.1.8** (final phase patch). Milestone branch
 merged to main and deleted — tags v0.1.0–v0.1.8 preserve the full
 history. Next milestone: v0.2 MVP (unblocked).
 
-## Milestone v0.2 — MVP (feature) — UNBLOCKED (prototype approved 2026-09-27)
+## Milestone v0.2 — MVP (feature) — COMPLETE (approved 2026-09-27)
 
 Phases renumbered from the original v1.0 plan (1-based within the milestone). Tags run on the v0.2.x line; MAJOR stays 0.
 
@@ -110,7 +110,24 @@ Phases renumbered from the original v1.0 plan (1-based within the milestone). Ta
 
 ### Phase 5 — Final Review + Ship (FINAL)
 - **Description**: Review + audit + milestone ship; final patch tag IS the MVP release. MAJOR stays 0 — the MVP ships as a 0.x release. v1.0.0 comes only after an owner-approved release decision.
-- **Status**: in progress (final phase — review complete, audit complete, ship v0.2.5 next; milestone merge HALTS at the owner approval gate per D-018)
+- **Status**: complete (PR #14 squash-merged 023667e, tag v0.2.5, release HTTP 201, phase branch deleted; review 4 P0 + 15 P1 — P0s attack-proven fixed; audit PASS-WITH-NOTES — criticals fixed; **owner approval RECORDED 2026-09-27** — decision commit 4721c2a, G-009 scope ratified; milestone merged to main, v0.2.5 = the MVP release)
+
+## Milestone v0.2 — COMPLETE (approved 2026-09-27)
+
+All requirements complete: REQ-01..26, REQ-31..34 (the MVP set). The
+approved MVP release is **v0.2.5** (final phase patch). Delivered: the
+FastAPI research engine (asyncio state machine, durable
+pause/cancel/resume), methodology framework (12 dials, Rapid Answer +
+Deep Report), five-adapter layer (Ollama cloud-first fallback,
+Tavily/DDG, storage, memory, secrets), the attack-proven trust loop
+(real quote anchoring, cited-scoped ≥99% liveness export gate, SSRF-
+guarded fetching, citation ledger, verification checklist), SSE live
+trace, OpenAPI-generated typed client behind the unchanged ApiClient
+boundary, a 14-attack adversarial suite, and the 3-click E2E on the
+real stack. G-009 ratified: live mode = core research loop only;
+library/settings/suggestions/refine/graph stay mock-backed until
+v0.3+. Milestone branch merged to main and deleted — tags
+v0.2.0–v0.2.5 preserve the full history. Next: v0.3 planning.
 
 ## Milestone Releases
 - **v0.1.4 = extended-prototype candidate** (superseded by the P5/P6 extension cycle)
@@ -118,7 +135,7 @@ Phases renumbered from the original v1.0 plan (1-based within the milestone). Ta
 - **v0.1.6 = extended-prototype candidate** (superseded by the P7/P8 extension cycle)
 - **v0.1.7 = ask suggestions + refine dialogue** (P7 patch)
 - **v0.1.8 = milestone release** (P8 final phase patch — the approved extended prototype release, pending owner decision)
-- **v0.2.x = MVP release** (MAJOR still 0; ship only if all v0.2 phases complete)
+- **v0.2.5 = milestone release** (P5 final phase patch — the approved MVP; owner approval recorded 2026-09-27, G-009 ratified)
 - If MVP scope extends: additional 0.x minor milestones (v0.3, …), each a full milestone cycle
 - **v1.0.0**: owner-approved release only — not created by the pipeline autonomously
 

.ciagent/config.json

@@ -2,18 +2,23 @@
   "ci_version": "0.7.0",
   "projects": [],
   "active_project": "researchx",
-  "milestone": "v0.2",
-  "milestone_name": "mvp",
+  "milestone": "v0.3",
+  "milestone_name": "next-milestone-planning",
   "milestone_type": "feature",
   "versioning": {
     "major_locked": true,
-    "major_lock_note": "MAJOR remains 0 until an owner-approved v1 release; the MVP may span multiple 0.x minor milestones; all pre-v1 ships are MINOR/PATCH only",
-    "tag_line": "v0.2.x",
-    "next_milestone": "v0.3+ (post-MVP backlog milestones)"
+    "major_lock_note": "MAJOR remains 0 until an owner-approved v1 release; all pre-v1 ships are MINOR/PATCH only",
+    "tag_line": "v0.3.x",
+    "next_milestone": "v0.3 scope definition pending owner direction (post-MVP backlog: live-bound library/settings/suggestions/refine, backend hosting, remaining 6 methodologies)"
   },
   "autonomy": {
     "level": "full",
-    "escalation_hooks": ["deploy", "delete_data", "merge_to_main", "prototype_approval"],
+    "escalation_hooks": [
+      "deploy",
+      "delete_data",
+      "merge_to_main",
+      "prototype_approval"
+    ],
     "decision_confidence_threshold": 0.6,
     "max_revision_iterations": 3,
     "clarify_budget": 10
@@ -37,9 +42,16 @@
   "secrets": {
     "env_file": ".ciagent/.env.secrets",
     "scopes": {
-      "release": ["GITEA_TOKEN"],
-      "model": ["OLLAMA_API_KEY", "OLLAMA_BASE_URL"],
-      "search": ["TAVILY_API_KEY"]
+      "release": [
+        "GITEA_TOKEN"
+      ],
+      "model": [
+        "OLLAMA_API_KEY",
+        "OLLAMA_BASE_URL"
+      ],
+      "search": [
+        "TAVILY_API_KEY"
+      ]
     }
   }
-}
+}

.ciagent/release/DEPLOY-RECORD.md

@@ -1,8 +1,8 @@
-# Deploy Record — UAT stagings of the v0.1 prototype
+# Deploy Record — UAT stagings and releases
 
-Owner-directed UAT deployments, recorded per commit discipline. The
-approval gate (REQ-62) stays closed; UAT variants stage review builds
-without minting release tags.
+Owner-directed deployments, recorded per commit discipline. Release
+deploys carry the owner approval (v0.1.8); UAT variants stage review
+builds without minting release tags.
 
 | Date | Version | Commit | Directive | Result |
 |---|---|---|---|---|
@@ -11,6 +11,8 @@ without minting release tags.
 | 2026-09-27 | v0.1.7-uat | 432d2c0 (P7 ship + boundary docs) | owner cadence: deploy after P7 and P8 | healthy — http://10.0.0.114:3000 |
 | 2026-09-27 | v0.1.8-uat | 93a7b57 (P8 ship — release candidate) | owner cadence: deploy after P7 and P8 | healthy — http://10.0.0.114:3000 |
 | 2026-09-27 | **v0.1.8 (release)** | 93a7b57 (tagged) | **owner approval recorded — milestone release published** | healthy — http://10.0.0.114:3000 |
+| 2026-09-27 | v0.2.5-uat | c28a97e (v0.2 milestone HEAD + v0.2.5 version strings) | owner: "deploy and validate against https://research.coreci.dev" | healthy — https://research.coreci.dev (HAProxy/SSL) |
+| 2026-09-27 | **v0.2.5 (release)** | b11b202 (main merge; tag v0.2.5) | **owner approval recorded (/ci-run APPROVED) — milestone release published; G-009 ratified** | serving — same container (v0.2.5-uat build = release content); no redeploy needed |
 
 ## v0.1.6-uat (extended prototype for owner review)
 
@@ -24,4 +26,25 @@ without minting release tags.
 - Rollback: `ssh root@10.0.0.114 'docker stop researchx; docker rename
   researchx-prev researchx; docker start researchx'`
 - The approval gate remains closed: milestone merge to main still halts
-  for the recorded owner decision (REQ-62)
+  for the recorded owner decision (REQ-62)
+
+## v0.2.5-uat (MVP release candidate, owner-directed)
+
+- Deployed via `bash .ciagent/release/deploy.sh v0.2.5-uat` — the v0.2
+  milestone HEAD (c28a97e: tag v0.2.5 + v0.2.5 About/package.json
+  version strings), per the owner's direct request to deploy and
+  validate against the public URL
+- Gates re-run at deploy time from the milestone HEAD: typecheck,
+  lint, test (97/97), build — green before sync
+- Image `researchx:v0.2.5-uat` + `latest` on the host; container
+  swapped, `researchx-prev` (v0.1.8) kept for rollback
+- Health: 2 checks; validated through the HAProxy SSL front:
+  https://research.coreci.dev — /ask /library /settings /choose all
+  200, root 307→/ask, TLS verified; served settings chunk carries
+  "v0.2.5 · MVP release candidate"; the RESEARCHX_API_MODE switch is
+  present in the served bundle (mock default — correct for a
+  frontend-only container; live mode additionally needs the backend
+  API on the host, which is v0.3+ deployment work)
+- The merge gate (D-018) remains closed: milestone → main still halts
+  for the recorded owner decision, with G-009 (live-mode scope)
+  presented at the same gate

.ciagent/release/UAT-v0.2.5.md

@@ -0,0 +1,87 @@
+# UAT Script — v0.2.5 (MVP release candidate)
+
+Deployment: https://research.coreci.dev (HAProxy → LXC container
+`researchx:v0.2.5-uat`, commit c28a97e, mock-backed frontend).
+
+Scope note (G-009): this container serves the v0.2.5 frontend with
+scripted mock data. The v0.2 engine (FastAPI, adapters, trust loop)
+is validated by the automated suites (129 backend + 97 frontend
+tests, 14 adversarial attacks, real-stack E2E) and runs via the
+README live-mode locally; hosting the backend is v0.3+ work. This
+UAT validates the release-candidate build of the product surface.
+
+## 1. Shell & navigation (REQ-63, REQ-66)
+
+1. Open https://research.coreci.dev → lands on **/ask** inside the app shell
+2. Sidebar: **New research / Library / Settings** nav present on every screen
+3. Top bar: press **⌘K** → navigation palette (screens + stored reports)
+4. Click the **avatar** (top right) → user menu: local profile, Settings, About
+5. Pass: shell persistent everywhere, honest preview-marked future slots
+
+## 2. Version check (this deploy)
+
+1. Sidebar → **Settings** → scroll to *About & version*
+2. Pass: reads **"v0.2.5 · MVP release candidate"** (confirms the deployed build)
+
+## 3. The ≤3-click happy path (REQ-61 / REQ-17 — core criterion)
+
+1. **/ask**: type a question → click **Research this** (click 1)
+2. **/choose**: pick a card (Deep Report is the recommended default) → **Start research** (click 2)
+3. **Plan & Run**: review the plan → **Approve plan** (click 3)
+4. Pass: exactly 3 clicks, defaults only, research running with a live trace
+
+## 4. Plan & Run (REQ-57)
+
+1. Plan approval UI shows sub-questions, source universe, outline
+2. Watch the live trace stream (scripted replay)
+3. Press **pause** → trace halts; **resume** → continues; **cancel** → terminal state
+4. Pass: all three controls behave; no lost events
+
+## 5. Reading Room + exports (REQ-58, REQ-59, REQ-34)
+
+1. Open the finished report from the run screen
+2. Hover/focus any **[n]** citation marker → the exact quoted passage appears
+3. Open the **citation ledger** panel: URL, quote, health, authority tier
+4. **Export Markdown** and **Export JSON** → real files download; citations survive as links
+5. Pass: quotes match exactly; files open; links intact
+
+## 6. Ask intelligence (REQ-67, REQ-68)
+
+1. **New research** → below the form: open-question suggestions appear
+2. Click one → the question box fills; **never auto-starts**
+3. Type a draft → **Refine question** → answer the 3 clarifying questions → **Use this** → refined question + context fill the form
+4. Try **Keep original** on a second draft → untouched; keyboard (Enter) works through both flows
+5. Pass: both helpers are opt-in, keyboard-accessible, drafts preserved on dismiss
+
+## 7. Library (REQ-64)
+
+1. Sidebar → **Library**: folder tree, auto-categorized (topic + methodology), sortable (recency/title)
+2. Open a stored report → its own Reading Room view
+3. **Connections** panel: shared-source ⇄ and topical → edges
+4. v2 previews: project graph + task inbox panels render
+5. Pass: folders, sorting, connections, previews all render from the fixture data
+
+## 8. Settings (REQ-65)
+
+1. API keys: masked (never raw); storage directory field
+2. Methodology defaults: resolved 12-dial display
+3. Appearance preview; About & version (step 2)
+4. Pass: everything honest and functional on mock data
+
+## Optional: hands-on the live engine (not on this URL)
+
+```bash
+# locally, two terminals:
+cd backend && uv sync && uv run uvicorn researchx.api.app:app --port 8000
+cd frontend && NEXT_PUBLIC_RESEARCHX_API_MODE=live corepack pnpm dev
+# then repeat steps 3-5 against the real engine (fake adapters, zero keys)
+```
+
+## Decision rubric (the gate this UAT feeds)
+
+- **Approve**: recorded via /ci-run → milestone merges to main,
+  v0.2.5 publishes as the MVP release, v0.3 planning unblocks
+  (with G-009 scope ratified: library/settings/suggestions/refine/
+  graph stay mock-backed until v0.3+)
+- **Request changes**: feedback becomes binding decisions for a
+  fix cycle (v0.1 precedent: two feedback cycles before approval)

.ciagent/release/VERSIONING.md

@@ -9,7 +9,7 @@ as established by the CIAgent branch strategy and `config.json`.
 | Milestone | Tags | Deployed by |
 |---|---|---|
 | v0.1 prototype | v0.1.0 … v0.1.8 | `bash .ciagent/release/deploy.sh v0.1.8` |
-| v0.2 MVP | v0.2.0 … | `bash .ciagent/release/deploy.sh v0.2.x` |
+| v0.2 MVP | v0.2.0 … v0.2.5 | `bash .ciagent/release/deploy.sh v0.2.5-uat` (staged) — see DEPLOY-RECORD.md |
 
 ## Rules
 

.gitea/workflows/ci.yml

@@ -0,0 +1,157 @@
+# .gitea/workflows/ci.yml - ResearchX phase-4 CI gate (researchx#24).
+#
+# This file IS the gate. The pre-code clause (coreci/company#105, c14057):
+# a code phase opens only when the product repo's gating workflow file has
+# dispatched at least one run on `main` and every job in that file is green
+# in that run. Until this file exists, coreci/researchx has no workflow and
+# no run at all - that is the case the clause was amended for (researchx#24,
+# c14093). A half-green pipeline does not open the phase either.
+#
+# Two jobs:
+#   backend  - uv + Python 3.12: ruff, mypy, pytest
+#   frontend - Node 22 + pnpm 12.6.0: typecheck, lint, test, build
+#
+# Runner label: `ubuntu-latest` - the org CI fleet's published label whose
+# image is docker.gitea.com/runner-images:ubuntu-latest (label map read at
+# source: coreci/nextcraft deploy/ci/docker-compose.yaml + deploy/ci/README.md,
+# R-3). The previous string `employee-runner` was a fleet NAME, not a label:
+# the employee fleet's labels are `employee-py` and `employee-coder` (read
+# from a live job log of this seat's own home), and the CI fleet's are node /
+# ubuntu-latest / python / release - no runner carried the old label, so a
+# merged file asking for it could still buy no run.
+#
+# Toolchain: measured, not assumed. From the runner's own logs (job 56393,
+# coreci/nova-platform, 2026-10-26T23:17Z, and job 57005, coreci/inboxos-v1,
+# 2026-10-27T03:01Z): the image carries python 3.12.3, pip, git, node (the
+# actions run in it), pypi REACHABLE and github REACHABLE; actions/checkout@v4,
+# actions/setup-python@v5 and actions/setup-go@v5 all run inside it. It does
+# NOT carry uv or pnpm, so this file installs them: uv from pypi (pip), pnpm
+# 12.6.0 through corepack - the repo's own documented way (README command map).
+# The gates are the repo's documented commands: backend `uv run ruff check src
+# tests`, `uv run mypy src`, `uv run pytest`; frontend `pnpm typecheck`,
+# `pnpm lint`, `pnpm test`, `pnpm build`. The frontend lane mirrors the
+# release image's own recipe (frontend/Dockerfile: node:22-alpine, corepack,
+# pnpm install --frozen-lockfile, pnpm build), so the gate tests what the
+# product ships.
+#
+# Owner of a red leg (the clause asks for the owner of the fix next to the
+# owner of the product line): toolchain / image / dispatch problems ->
+# coreci-sre (employee-runner-fleet + gitea-instance); product-line problems
+# -> coreci-researchx-po. Approval for this file rides the merge request
+# (merge = approval, constitution v1.3).
+
+name: ci
+
+on:
+  push:
+  pull_request:
+    branches: ["main"]
+  workflow_dispatch:
+
+jobs:
+  backend:
+    name: "backend (uv, Python 3.12: ruff/mypy/pytest)"
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      # uv is not in the CI image; pypi is reachable from it (measured). The
+      # install is a toolchain leg, not a product gate: the gates still run
+      # from the repo's own committed lockfile (backend/uv.lock).
+      - name: Install uv (from pypi)
+        run: |
+          set -eu
+          python -m pip install --upgrade uv
+          uv --version
+
+      - name: Install dependencies (uv, from the committed lockfile)
+        working-directory: backend
+        run: uv sync --frozen
+
+      - name: Lint (ruff)
+        working-directory: backend
+        run: uv run ruff check src tests
+
+      - name: Typecheck (mypy)
+        working-directory: backend
+        run: uv run mypy src
+
+      - name: Test (pytest)
+        working-directory: backend
+        run: uv run pytest
+
+  frontend:
+    name: "frontend (Next.js on pnpm: typecheck/lint/test/build)"
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      # Node 22 to mirror the release image (frontend/Dockerfile: node:22).
+      - name: Setup Node 22
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Setup Python 3.12 (for the real-stack e2e bridge)
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv (from pypi)
+        run: |
+          set -eu
+          python -m pip install --upgrade uv
+
+      # pnpm 12.6.0 is pinned by frontend/package.json `packageManager`;
+      # corepack reads it from there. If the image carries no corepack, npm
+      # installs the same pinned version.
+      - name: pnpm 12.6.0 (corepack, pinned by frontend/package.json)
+        working-directory: frontend
+        run: |
+          set -eu
+          node --version
+          corepack enable pnpm 2>/dev/null || true
+          if ! pnpm --version >/dev/null 2>&1; then
+            npm i -g pnpm@12.6.0
+          fi
+          test "$(pnpm --version)" = "12.6.0"
+
+      - name: Install dependencies (from the committed lockfile)
+        working-directory: frontend
+        run: pnpm install --frozen-lockfile
+
+      # frontend/src/lib/api/e2e-real-stack.test.ts drives the real FastAPI
+      # stack: it spawns `uv run python -m researchx.api.dev_bridge` from
+      # ../backend (loopback :8000, fakes only, zero API keys). Without a
+      # synced backend venv that test cannot come up, so the lane provisions
+      # it. Provisioning only - the backend gates stay in the backend job.
+      - name: Backend venv for the real-stack e2e bridge
+        working-directory: backend
+        run: uv sync --frozen
+
+      - name: Typecheck
+        working-directory: frontend
+        run: pnpm typecheck
+
+      - name: Lint
+        working-directory: frontend
+        run: pnpm lint
+
+      - name: Test
+        working-directory: frontend
+        run: pnpm test
+
+      - name: Build
+        working-directory: frontend
+        env:
+          NEXT_TELEMETRY_DISABLED: "1"
+        run: pnpm build

README.md

@@ -1,8 +1,15 @@
 # ResearchX
 
+**TL;DR** — ResearchX turns one question into a cited research report: pick a method, approve the plan, and the engine visits real web sources, with every claim anchored to a quoted passage from a page it actually read. The engine milestone (v0.2.5) is shipped and owner-approved; hosting goes live next (v0.3, in progress).
+
+- **What** — FastAPI backend (planning, search, extraction, verification, export gates) plus a Next.js frontend; the full test suite runs with zero API keys.
+- **Why** — Readers can check every citation back to its source passage; runs are resumable from durable state.
+- **Action** — no action — FYI. Developers: see the Quickstart below.
+- **Details** — `frontend/README.md` (web app); `.ciagent/` (pipeline state and roadmap).
+
 A deep-research studio where you bring your own model, storage, and memory; choose a research methodology before a single query fires; and every claim in the final report is anchored to a visited, verified, quotable source.
 
-**Status: MVP in development (milestone v0.2)** — the approved v0.1 prototype frontend (mock-backed) plus the FastAPI backend, research engine, adapter layer, and trust loop. The frontend runs standalone on mock data; live backend mode arrives with v0.2 phase 3.
+**Status: MVP shipped (v0.2.5, owner-approved 2026-09-27)** — the full research engine (FastAPI + asyncio state machine + adapter layer + attack-proven trust loop) behind the v0.1 frontend. Live mode covers the core research loop (G-002/G-009): the engine runs locally per the quickstart; library/settings/suggestions/refine stay mock-backed until v0.3+.
 
 ## Quickstart
 

backend/src/researchx/api/app.py

@@ -226,6 +226,7 @@ def create_app(
             storage=storage,
             registry=registry,
             event_bus=bus,
+            on_complete=runs.note_completed,
         )
         probe_data: dict[str, Any] | None = None
         if supports_probe(model):
@@ -240,9 +241,7 @@ def create_app(
         runs.add(run_id, actor, task, bus)
 
         async def _watch() -> None:
-            state = await task
-            if state.state == RunStateName.DONE:
-                runs.note_completed()
+            await task
 
         asyncio.create_task(_watch())
         return _summary(run_id)

backend/src/researchx/engine/actor.py

@@ -1,4 +1,5 @@
 import asyncio
+from collections.abc import Callable
 from datetime import UTC, datetime
 from typing import Any
 
@@ -34,6 +35,7 @@ class RunActor:
         storage: LocalStorageAdapter,
         registry: MethodologyRegistry,
         event_bus: EventBus,
+        on_complete: Callable[[], None] | None = None,
     ) -> None:
         self._config = run_config
         self._model = model
@@ -41,6 +43,7 @@ class RunActor:
         self._storage = storage
         self._registry = registry
         self._bus = event_bus
+        self._on_complete = on_complete
         self._store = EvidenceStore()
         self.state = RunState(
             run_id=run_config.run_id,
@@ -83,6 +86,8 @@ class RunActor:
     async def _checkpoint(self, target: RunStateName) -> None:
         if self.state.state != target:
             self.state.transition(target)
+            if target is RunStateName.DONE and self._on_complete is not None:
+                self._on_complete()
         await self._persist()
 
     async def _wait_if_paused(self) -> None:

frontend/README.md

@@ -1,5 +1,12 @@
 # ResearchX Frontend
 
+**TL;DR** — This is the ResearchX web interface: ask a question, choose a research method, approve the plan, watch the live trace, read the cited report. The prototype runs entirely on scripted sample data — no API keys, no backend, no network — so the full product journey is tryable today.
+
+- **What** — A Next.js app (ask, choose, run, report, library, settings) rendering mock data through one typed client interface.
+- **Why** — The journey is checkable end-to-end before live inference exists.
+- **Action** — no action — FYI. Developers: Quickstart below (Node 20+, pnpm).
+- **Details** — Root `README.md`: backend engine, live mode, architecture.
+
 The prototype frontend for ResearchX — methodology-driven deep research
 with a trust loop. This milestone (v0.1) runs **entirely on mock data**:
 no API keys, no env vars, no network calls beyond static assets.

frontend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@researchx/frontend",
-  "version": "0.1.8",
+  "version": "0.2.5",
   "private": true,
   "packageManager": "pnpm@12.6.0",
   "scripts": {

frontend/src/components/settings-view.test.tsx

@@ -107,6 +107,6 @@ describe("SettingsView (REQ-65)", () => {
     expect(screen.getByText("preview", { exact: true })).toBeInTheDocument();
 
     expect(screen.getByText(/About & version|About and version/i)).toBeInTheDocument();
-    expect(screen.getByText(/v0\.1\.8 · prototype/i)).toBeInTheDocument();
+    expect(screen.getByText(/v0\.2\.5 · MVP release candidate/i)).toBeInTheDocument();
   });
 });

frontend/src/components/settings-view.tsx

@@ -244,8 +244,9 @@ export function SettingsView() {
             visited-only citations, three clicks to a trustworthy report.
           </p>
           <p className="mt-2 text-caption text-ink-faint">
-            v0.1.8 · prototype — runs on scripted mock data; the engine,
-            adapters, and trust loop arrive in v0.2.
+            v0.2.5 · MVP release candidate — mock-backed by default; the
+            engine, adapters, and trust loop ship with v0.2 (live mode:
+            NEXT_PUBLIC_RESEARCHX_API_MODE=live).
           </p>
         </section>