feat(api,ui): showcase pipeline agent ops final polish (PRP-41)

[w7-mgfcode]

Summary

PRP-41 — fourth and FINAL slice of the /showcase upgrade epic (PRP-38..41). Adds two pipeline phases (agents HITL + ops snapshot) plus cross-cutting UI polish that closes #311.

Closes: #321 (execution issue) · #311 (Phase accordion onValueChange bug)

What ships

Backend (app/features/demo/pipeline.py)

• step_agent_hitl_flow — HITL approval round-trip on the experiment agent. Drives POST /agents/sessions + /chat + /approve via ASGITransport; emits an intermediate step_complete (status=running, awaiting_approval=true) for the FE Approve button; absorbs the 400 "No pending action" when the FE pre-empts the auto-approve; 90 s hard timeout falls back to skip so a hung agent never wedges the run.
• step_ops_snapshot — three GETs (/ops/summary, /ops/retraining-candidates, /ops/model-health) → 5-key KPI payload. warn (never fail) on all-three-failed.
• _Client.yield_event opt-in hook + run_pipeline event-sink drain. Orchestrator stamps step_index / total_steps / phase_index / phase_total / phase_name on every drained event before the terminal step_complete (design Z, verified viable by Task 1 contract probe).
• _phase_table() — design Z: unified agents phase id for BOTH scenarios; SHOWCASE_RICH swaps step_agent → step_agent_hitl_flow and appends ops_snapshot under a new ops phase before cleanup. SHOWCASE_RICH = 24 rows / 10 phases; DEMO_MINIMAL = 11 rows (shape unchanged under new agents phase id).

Frontend (frontend/src/)

• PHASE_DEFS.ts — design Z restructure: BOTH the legacy agent step and the new agent_hitl_flow live under the unified agents phase id; new DEMO_MINIMAL_ONLY_STEP_NAMES set complements SHOWCASE_RICH_STEP_NAMES. Lockstep test pins 24 tuples / 10 phases.
• DemoPhasePanel.tsx — adds onValueChange handler + local useState (closes fix(ui): unlock showcase phase accordion after completion #311 / D10): post-pipeline_complete the operator can finally expand any phase without snapping back to the fallback.
• demo-step-card.tsx — HitlFlowSummary chip-line + OpsSnapshotMiniGrid + one-click ApproveButton (renders ONLY when status=running && awaiting_approval=true).
• showcase.tsx — five chrome additions:
  • ShowcaseKpiStrip — 5-tile KPI strip at the top.
  • RunHistoryStrip — localStorage FIFO 5 with Replay button (key forecastlab.showcase.runs.v1).
  • Stop button (visible mid-run) — closes the WS so the backend's WebSocketDisconnect releases _pipeline_lock.
  • InspectArtifactsPanel — 10 deep-link cards rendered after pipeline_complete.
  • resolveInspectHref extended with agent_hitl_flow → CHAT, ops_snapshot → OPS.
• use-demo-pipeline.ts — stop() callback exposed via UseDemoPipelineResult; DemoSummary.v2RunId added (mapped from pipeline_complete.data.v2_run_id).

Docs

• docs/user-guide/showcase-walkthrough.md — drops 7 "planned" markers across PRP-38/39/40/41 phases; adds concrete prose for Agents (HITL) + Ops snapshot + 5 polish items + performance budgets table refresh + screenshot placeholders.
• docs/_base/RUNBOOKS.md — 5 new failure-mode entries (23–27): agent_hitl_flow no-key / timeout / no-trigger, ops_snapshot all-failed, Stop button mid-run.

Hard invariants honoured

• Backend contracts read-only. Zero new endpoints, zero new schemas, zero migrations.
• Vertical-slice rule. git grep -nE "from app\.features\.(agents|ops|registry|scenarios|rag)" app/features/demo/ empty.
• WebSocket additive only. New keys ride inside StepEvent.data: dict[str, Any]; no schema bump; no new event_type values (just two new phase id VALUES: "agents" and "ops").
• agent_require_approval untouched (save_scenario already listed).
• No CRLF/LF normalisation bundled in (per memory anchor [[repo-line-endings-crlf]]).

Task 1 contract probe

Output: PRPs/ai_docs/prp-41-contract-probe-report.md (407 lines). Zero field-level drift; all 5 unresolved contract assumptions resolved; one wording patch applied to PRP body § Task 9 (filter restructure for design Z).

Validation results

Gate	Result
uv run ruff check . && uv run ruff format --check .	✅
uv run mypy app/	✅ Zero PRP-41-introduced errors (3 pre-existing xgboost stub errors documented in PRP body)
uv run pyright app/	✅ Same — demo slice 0 errors
uv run pytest -m "not integration"	✅ 1635 passed, 12 skipped
cd frontend && pnpm tsc --noEmit -p tsconfig.app.json	✅ Zero PRP-41-introduced errors (3 fewer pre-existing errors than baseline)
cd frontend && pnpm test --run	✅ 249 tests passed across 35 files
uv run pytest -m integration tests/test_e2e_demo.py::test_run_demo_showcase_rich_full_epic	✅ Green (with documented PRP-39/40 cascade tolerance)
git grep "from app\.features\.(agents|ops|registry|scenarios|rag)" app/features/demo/	✅ Empty

Known pre-existing issue surfaced (NOT a PRP-41 regression)

The full showcase_rich flow hits a documented PRP-39/40 cascade bug on a fresh-DB run: safer_promote_flow swaps the demo-production alias to a placeholder run whose artifact_uri _parse_artifact_key cannot parse, breaking the downstream scenario_simulate_and_save step. Documented in RUNBOOKS.md entry 18; tracked in test_run_demo_showcase_rich_full_epic as a tolerated cascade (the test still passes when this fires because all PRP-41 steps are downstream and never run — when they DO run, the PRP-41 contract assertions fire). Fixing this cascade is out of PRP-41 scope; a follow-up PRP should address it.

Out of scope (explicit)

• No new backend endpoints, no new schemas, no Alembic migrations.
• No widening of agent_require_approval.
• No CRLF→LF line-ending normalisation.
• No PRP-39/40 cascade fix (see Known issue above).

Test plan

• All unit gates green (ruff / mypy / pyright / pytest "not integration").
• All frontend gates green (vitest + tsc).
• Vertical-slice grep guard empty.
• PRP-41 integration test green.
• Manual dogfood D1–D10 (deferred — requires browser session against running stack).
• CI green on dev-targeted PR.

Contract probe report

PRPs/ai_docs/prp-41-contract-probe-report.md — Task 1 deliverable, field-for-field verification of every cited backend + frontend contract on dev@58d593a. Documents the four assumption resolutions and the one PRP wording patch applied before implementation.

[sourcery-ai]

Sorry @w7-mgfcode, your pull request is larger than the review limit of 150000 diff characters

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 843ebc9e-2c76-43b5-b05e-4851fbeee99c

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/showcase-41-agent-ops-polish

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}