---
phase: 03-unified-runtime-workspace
plan: "01"
subsystem: ui
tags: [runtime, typescript, react, diagnostics]

# Dependency graph
requires:
  - phase: 02-lifecycle-command-safety
    provides: lifecycle metadata (active_command, last_command_result), applyImpact, restart-required field list
provides:
  - RuntimeWorkspaceSummary type with statusLabel, modeLabel, endpointLabel, modelLabel
  - RuntimeWorkspaceHealth type with headline, detail, tone
  - getRuntimeWorkspaceSummary helper function
  - getRuntimeHealthSummary helper function
  - workspaceSummary and workspaceHealth from useRuntimeManager hook
affects: [03-02, 03-03]

# Tech tracking
tech-stack:
  added: []
  patterns: [manager-owned diagnostic contract, derived workspace summary]

key-files:
  created: []
  modified:
    - tauri-app/src/features/runtime/types.ts - Added RuntimeWorkspaceSummary, RuntimeWorkspaceHealth types
    - tauri-app/src/features/runtime/runtime-utils.ts - Added getRuntimeWorkspaceSummary, getRuntimeHealthSummary
    - tauri-app/src/features/runtime/useRuntimeManager.ts - Exposed workspaceSummary, workspaceHealth
    - tauri-app/src/features/runtime/components/RuntimeSurface.test.tsx - Added regression tests

key-decisions:
  - "Reuse existing restart-impact field list and lifecycle labels instead of creating parallel heuristics"
  - "Derive diagnostics from backend-owned snapshot fields (status, ready, process_running, resolved_url, config.*, binary_path, last_error)"

patterns-established:
  - "Manager-owned workspace summary: single authoritative source for endpoint, mode, model, readiness"
  - "Health tone mapping: neutral=remote, success=ready, warning=starting/stopping/degraded, danger=error"

requirements-completed: [WORK-01, DIAG-01]

# Metrics
duration: 6min
completed: 2026-03-29
---

# Phase 3 Plan 1: Unified Runtime Workspace Contract

**Manager-owned runtime workspace summary with health diagnostics derived from backend snapshot fields**

## Performance

- **Duration:** 6 min
- **Started:** 2026-03-29T17:30:00Z
- **Completed:** 2026-03-29T17:36:00Z
- **Tasks:** 2
- **Files modified:** 4

## Accomplishments
- Added typed RuntimeWorkspaceSummary and RuntimeWorkspaceHealth interfaces to the runtime types
- Implemented pure helper functions getRuntimeWorkspaceSummary and getRuntimeHealthSummary in runtime-utils.ts
- Exposed workspaceSummary and workspaceHealth from useRuntimeManager hook
- Added regression tests proving the manager can describe the full runtime workspace

## Task Commits

Each task was committed atomically:

1. **Task 1: Add shared runtime workspace summary and health-diagnostic types** - `20aa158` (feat)
2. **Task 2: Expose the unified workspace contract from the runtime manager** - `20aa158` (feat)

**Plan metadata:** `20aa158` (docs: complete plan)

## Files Created/Modified
- `tauri-app/src/features/runtime/types.ts` - Added RuntimeWorkspaceSummary, RuntimeWorkspaceHealth, RuntimeWorkspaceHealthTone, RuntimeWorkspaceSectionValue types
- `tauri-app/src/features/runtime/runtime-utils.ts` - Added getRuntimeWorkspaceSummary and getRuntimeHealthSummary helper functions
- `tauri-app/src/features/runtime/useRuntimeManager.ts` - Added workspaceSummary and workspaceHealth to return value
- `tauri-app/src/features/runtime/components/RuntimeSurface.test.tsx` - Added 6 regression tests for new workspace contract

## Decisions Made
- Reuse existing restart-impact field list (connection_mode, model_path, addr, gpu_layers, ctx_size) from runtime-utils.ts
- Reuse existing lifecycle labels and getRuntimeStateLabel instead of creating parallel heuristics
- Derive health diagnostics from backend-owned snapshot fields (status, ready, process_running, resolved_url, config.*, binary_path, last_error)
- Health tone mapping: remote=neutral, ready=success, starting/stopping/degraded=warning, error=danger

## Deviations from Plan

None - plan executed exactly as written.

## Issues Encountered
None

## Next Phase Readiness
- Types and helpers ready for Plan 03-02 (unified runtime workspace component)
- Manager contract ready for shell integration in Plan 03-03
- Tests verify workspace summary and health work for ready, degraded, and remote modes

---
*Phase: 03-unified-runtime-workspace*
*Completed: 2026-03-29*