ForgeLM/.planning/phases/03-unified-runtime-workspace/03-RESEARCH.md

# Phase 3 Research: Unified Runtime Workspace

**Date:** 2026-03-29
**Source:** Manual orchestration fallback in current session (subagent spawning unavailable in this environment)

## Goal to Plan For

Phase 3 must turn the current runtime controls into one authoritative workspace so the user can:

- manage runtime status, lifecycle actions, and settings from one place instead of bouncing between a summary card and a separate drawer (`WORK-01`)
- see actionable runtime health context, including readiness, endpoint or mode, active model, and failure guidance, in that same workspace (`DIAG-01`)
- keep the Phase 1 draft-safety and Phase 2 lifecycle-safety rules intact while consolidating the UI

## Current Implementation Findings

### Current runtime workspace is split across two UI surfaces

- `tauri-app/src/components/Sidebar.tsx` renders `RuntimeStatusCard` directly in the sidebar and opens `RuntimeSettingsDrawer` as a separate modal-like surface.
- `tauri-app/src/features/runtime/components/RuntimeStatusCard.tsx` shows status, model, endpoint summary, and start or stop actions.
- `tauri-app/src/features/runtime/components/RuntimeSettingsDrawer.tsx` holds the editable draft form, lifecycle apply guidance, Hugging Face search, managed library state, and save or start actions.
- The split means operators still move between a status surface and a settings surface to understand or fix runtime issues, which conflicts with the Phase 3 goal.

### The manager already has the right low-level state, but not a unified workspace contract

- `tauri-app/src/features/runtime/useRuntimeManager.ts` already preserves the Phase 1 draft model (`liveSnapshot`, `savedBaseline`, `draftConfig`, `draftFields`) and the Phase 2 lifecycle model (`activeLifecycleCommand`, `lastLifecycleResult`, `lifecycleBusy`, `applyImpact`).
- That hook does not yet expose a manager-owned summary of runtime health, endpoint or mode context, saved-versus-draft setting context, or action guidance that multiple UI sections can share.
- `tauri-app/src/features/runtime/runtime-utils.ts` derives labels such as `Ready`, `Attention needed`, and `Local API offline`, but it stops short of producing a richer diagnostic summary for a consolidated workspace.

### Diagnostics already exist in the snapshot, but presentation is fragmented

- The Tauri backend snapshot in `tauri-app/src-tauri/src/runtime/types.rs` and `tauri-app/src-tauri/src/runtime/state.rs` already provides `status`, `ready`, `process_running`, `resolved_url`, `binary_path`, `last_error`, `active_command`, `last_command_result`, and `config`.
- `tauri-app/src-tauri/src/runtime/state.rs` sets degraded health with `health_check_failed` and preserves explicit lifecycle result metadata, which means the frontend already has enough raw data to show actionable health context.
- Today that data is split between `RuntimeStatusCard` error/result banners and `RuntimeSettingsDrawer` apply guidance, so the user must infer the full runtime picture from two places.

### Existing behavior that Phase 3 must preserve

- Draft safety from Phase 1: dirty drafts stay stable across polling in `useRuntimeManager.ts`, and invalid or pending draft values stay visible in `RuntimeSettingsDrawer.tsx`.
- Lifecycle safety from Phase 2: explicit start or stop progress, completion results, blocked states, and restart-required apply impact are already covered in `RuntimeStatusCard.tsx`, `RuntimeSettingsDrawer.tsx`, and `RuntimeSurface.test.tsx`.
- Local-first onboarding behavior: the workspace already supports browsing model folders, adding files, searching Hugging Face, and saving plus starting the local API from one draft session.

### Current shell integration

- `tauri-app/src/App.tsx` passes the full runtime manager into `Sidebar` and uses `useRuntimeReadyModelRefresh` to refresh models once the runtime becomes ready.
- The runtime UI lives entirely in the sidebar shell, so Phase 3 can stay inside the existing Tauri + React architecture without introducing a new global store.
- `tauri-app/src/components/ChatView.tsx` relies on the runtime connection output for chat requests but does not currently render the authoritative runtime workspace itself.

### Existing tests and patterns

- `tauri-app/src/features/runtime/components/RuntimeSurface.test.tsx` is already the main integration-style harness for runtime workspace behavior, including draft safety, lifecycle status, degraded health, managed library state, and apply guidance.
- Phase 2 plan files show the expected executable PLAN.md format: frontmatter with `wave`, `depends_on`, `files_modified`, `requirements`, and `must_haves`, followed by XML tasks with mandatory `read_first` and `acceptance_criteria` blocks.

## Gaps Phase 3 Must Close

1. The workspace summary is split. Status and actions are in `RuntimeStatusCard`, while actionable settings and most health guidance live in `RuntimeSettingsDrawer`.
2. Diagnostics are not centralized. The user can see `last_error`, lifecycle result banners, apply guidance, endpoint details, and model context, but not in one coherent workspace.
3. The sidebar shell still treats runtime management as an overlay flow rather than the primary authoritative workspace.
4. There is no shared runtime-workspace view model that turns raw snapshot fields into stable UI sections for status, health, actions, and saved-versus-draft context.

## Planning Implications

Phase 3 should be split into three execution plans:

1. **Manager-owned workspace contract** - derive one shared runtime-workspace summary and diagnostic model from the existing snapshot, draft, and lifecycle state.
2. **Unified runtime workspace component** - build one component that combines status, actions, health guidance, and draft editing using the manager contract.
3. **Shell integration and split-surface removal** - wire the unified workspace into the sidebar and app shell so it becomes the only authoritative runtime control surface.

## Concrete Decisions for the Plans

- Keep the Phase 1 draft model intact; Phase 3 should compose on top of `liveSnapshot`, `savedBaseline`, `draftConfig`, and `draftFields` rather than replacing them.
- Keep the Phase 2 lifecycle contract intact; Phase 3 should reuse `active_command`, `last_command_result`, and `applyImpact` instead of re-inventing busy or restart heuristics.
- Treat these snapshot fields as the authoritative runtime health inputs: `status`, `ready`, `process_running`, `resolved_url`, `config.connection_mode`, `config.model_path`, `binary_path`, and `last_error`.
- Keep `RuntimeSurface.test.tsx` as the main regression harness for the consolidated workspace, adding assertions for the new unified layout instead of scattering tests across new harnesses.
- Preserve local-first model management inside the unified workspace: managed library state, scanned folders, ad hoc files, and Hugging Face search should still be available where the user edits runtime settings.

## Risks

- If the unified workspace duplicates logic instead of consuming a shared manager summary, status and diagnostics will drift between sections.
- If consolidation regresses Phase 1 draft preservation, the new workspace will feel more coherent but less trustworthy.
- If the shell keeps both the old status card and the new workspace active, the user will still have split authority and the phase goal will not be met.
- If mobile sidebar layout is not updated with the new workspace footprint, the authoritative surface may be harder to use than the split version.

## Recommended Verification Focus

- `tauri-app/src/features/runtime/components/RuntimeSurface.test.tsx` coverage for unified status, diagnostics, draft editing, and lifecycle actions in one surface
- TypeScript build verification after `Sidebar.tsx`, `App.tsx`, and runtime component contracts change together
- Assertions that split-surface wiring is removed or reduced to one authoritative runtime workspace entry point