stack/docs/scratchpads/webui-p3r1-routing-mcp.md

P3-R1 — Routing Health Enum + /mcp Wiring Scratchpad

Task: P3 hands-on acceptance blockers #1 and #5 Mission: mvp-20260312 (active) Branch: feat/webui-p3r1-routing-mcp from origin/next Required base: 20718b5a273d243363a4f5cbef5bbf692a805bdb Tracking ref: Direct P3-R1 author brief; no provider issue supplied; no PR or merge authorized Started: 2026-08-11T14:52:52-05:00

Objective

Fix exactly two P3 acceptance blockers:

1. Make routing consume the canonical ProviderHealthStatus enum, with healthy and degraded routable and down non-routable, at both routing decision sites.
2. Wire McpClientModule into CommandsModule, make McpClientService required, remove the unreachable unavailable-service branch, and prove /mcp status reaches the client.

Explicitly excluded: provider registry/adapters, provider.service.ts, agent.service.ts, chat.gateway.ts, fallback membership, task classification, selector UI, conversation resume, reload UX, WS/origin/handshake behavior, dependencies/lockfile, and apps/web/** changes.

Plan

1. Confirm exact base/branch and inspect every cited source/test anchor plus all direct CommandExecutorService construction sites.
2. Record baseline gateway and focused routing/commands/MCP test totals.
3. Add regression tests first and run focused tests to capture expected RED failures.
4. Apply only the typed routing helper/signature changes and required MCP module/constructor/guard changes; update impossible up fixtures.
5. Run focused tests, all user-required verification gates, lockfile/scope/diff checks, and record counts.
6. Obtain independent spec and code/security review; remediate any findings and repeat affected gates.
7. Commit conventionally, run the pre-push queue guard, and push only the feature branch (no PR or merge).

Budget

No explicit token cap supplied. Working soft cap: 30K tokens, based on two bounded gateway bug fixes, focused TDD, full gateway/root verification, independent review, and branch delivery. One coding worker will execute serially; reviews will be independent and serial to avoid worktree collisions.

Startup Evidence

• git fetch origin rc=0.
• origin/next confirmed exactly 20718b5a273d243363a4f5cbef5bbf692a805bdb.
• Local and remote feat/webui-p3r1-routing-mcp were absent before creation.
• Branch creation rc=0; HEAD equals the required base.
• Harness-owned .mosaic/orchestrator/session.lock was already dirty and remains excluded from staging/commit.

Baseline Evidence

• Gateway full suite: rc=0; 64 files / 693 tests passed, 7 files / 17 tests skipped (71 files / 710 tests total).
• Routing sub-suite (src/agent/routing): rc=0; 3 files / 105 tests passed.
• Commands/MCP sub-suite (src/commands, src/mcp-client): rc=0; 6 files / 76 tests passed.

TDD and Implementation Evidence

• Routing RED: after canonical fixture/test changes but before the service fix, focused routing run returned rc=1 with 15 failed / 91 passed (106) because the old up/ok gates rejected healthy and degraded.
• Routing GREEN: canonical ProviderHealthStatus map types, one isRoutable helper, and both comparison sites corrected; focused routing suite passed.
• MCP behavior test now drives /mcp status through a required mock client and asserts the client is called, success is returned for zero servers, and the former unavailable message is absent.
• MCP wiring mutation RED used the final Reflect.getMetadata('imports', CommandsModule) assertion with only the production McpClientModule import/registration temporarily removed: rc=1, exact failure expected [GCModule, …] to include McpClientModule.
• MCP wiring GREEN after byte-for-byte production restoration: rc=0. Temporary mutation did not remain.
• Every direct new CommandExecutorService(...) test construction now supplies a non-null MCP client mock.
• Initial Codex worker launch failed rc=1 from missing OpenAI bearer authentication. First Mosaic Claude launch failed rc=1 because Distrobox-local runtime contracts were absent; retry with the supported host MOSAIC_HOME=/home/jwoltje/.config/mosaic succeeded.

Review Evidence

• Independent spec review: approve, 0 blockers, scope OK.
• Independent code/security review: approve, 0 blockers, 0 critical/high security findings. It suggested an actual module-wiring assertion, which was added with valid mutation RED/GREEN evidence.
• Independent final re-review after remediation: approve, 0 blockers, 0 critical/high security findings, no remaining findings.
• Optional missing-provider/undefined test suggestion was not adopted: the brief explicitly requires the three canonical statuses (healthy, degraded, down) and forbids scope expansion; runtime behavior for absent keys remains undefined → non-routable through the required helper signature.

Documentation Assessment

• docs/PRD.md already requires provider fallback/routing and MCP capability; this increment restores implementation to those existing contracts.
• No public API endpoint, payload schema, auth/permission rule, navigation, deployment procedure, or new user workflow changes. OpenAPI, endpoint index, user/admin/developer guides, and sitemap are therefore N/A for this bounded repair.
• This append-only scratchpad is the implementation, TDD, review, and verification record. Canonical docs remain in-repo; no publishing action is in scope.

Final Verification Evidence

All required and repository-situational gates completed with rc=0:

Gate	Result
pnpm install --frozen-lockfile	rc=0
Gateway typecheck	rc=0
Gateway lint	rc=0
Routing focused suite	rc=0; 3 files / 106 tests
Commands/MCP focused suite	rc=0; 6 files / 78 tests
Gateway full suite	rc=0; 64 files / 696 tests passed; 7 files / 17 tests skipped
Gateway build	rc=0
Root typecheck	rc=0; 45/45 tasks
Web test	rc=0; 19 files / 154 tests
Root lint	rc=0; 25/25 tasks
Root format check	rc=0
git diff --check	rc=0

• Gateway suite before→after: 693→696 passing tests; skipped remained 17 (total 710→713).
• Routing focused before→after: 105→106 passing tests.
• Commands/MCP focused before→after: 76→78 passing tests.
• pnpm-lock.yaml SHA-256 before/after frozen install: 9acaa89d213b3281e757b6edf6fdb8727176570d725b78a0de234c61a7f3c332; diff versus origin/next rc=0.
• Verified no changed path under apps/web/**, provider service/adapters, agent.service.ts, chat.gateway.ts, or lockfile.
• Verified both McpClientModule production wiring lines remain and no impossible up/ok routing status checks/fixtures remain.
• Verified code/test diff SHA-256: 27b41a855084b9dd85a7bc2a79fa3251d114ee226a4f1b835e65134c25a4f5a8.

Delivery State

Implementation, testing, documentation assessment, and independent review are complete. Remaining authorized actions: format this final scratchpad append, create one conventional commit, run the required push queue guard, and push only feat/webui-p3r1-routing-mcp; no PR or merge.