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

The workspace summary is split. Status and actions are in RuntimeStatusCard, while actionable settings and most health guidance live in RuntimeSettingsDrawer.
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.
The sidebar shell still treats runtime management as an overlay flow rather than the primary authoritative workspace.
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:

Manager-owned workspace contract - derive one shared runtime-workspace summary and diagnostic model from the existing snapshot, draft, and lifecycle state.
Unified runtime workspace component - build one component that combines status, actions, health guidance, and draft editing using the manager contract.
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

7.8 KiB Raw Blame History