# Watch + Helm Reorganization

**Date**: 2026-02-26
**Status**: Approved

## Problem

Session observability is scattered across three directories with conflated concerns:

- `supervisor/watch/` — mixes UI (grid, recap pages) with backend (API, DB, state, hooks)
- `chronicle/` — mixes UI (8 Gradio tabs) with backend (session analysis, stats)
- `supervisor/` — auto-respond logic buried alongside unrelated UI code

## Design

Split into two top-level projects with clean frontend/backend separation:

### `watch/` — Session Dashboard (UI)

Everything you look at. One place to see all session activity, live and historical.

**From `supervisor/watch/`:**
- `grid_view.py` → `watch/grid.py` — session card grid
- `overview.py` → `watch/overview.py` — data layer (iTerm2 + DB joins)
- `idle_recap.py` → `watch/recap.py` — recap HTML rendering
- `app.py` → `watch/app.py` — Gradio dashboard
- `autonomous_view.py` → `watch/autodo_view.py`

**From `chronicle/`:**
- `ui.py` → `watch/chronicle.py` — Gradio tabs entry point
- `ui_daily.py`, `ui_gantt.py`, `ui_live.py`, `ui_projects.py`, `ui_timeline.py` → `watch/`
- `topic_graph.py` → `watch/topic_graph.py` — D3 force-directed graph

### `helm/` — Session Engine (Backend)

Sees everything, can act. Hooks, state tracking, auto-respond, analysis, coordination.

**From `supervisor/watch/`:**
- `api.py` → `helm/api.py` — FastAPI server (hooks, hist, state, recap, search)
- `db.py` → `helm/db.py` — watch DB
- `state_poller.py` → `helm/state_poller.py`
- `iterm2d_health.py` → `helm/iterm2d_health.py`

**From `supervisor/core/`:**
- `session.py`, `policy.py`, `decision.py`, `iterm2.py` → `helm/respond/`

**From `supervisor/sidekick/`:**
- `hooks/handler.py` → `helm/hooks/handler.py`
- `inbox.py` → `helm/inbox.py`

**From `supervisor/autonomous/`:**
- `planner.py`, `todo.py`, etc. → `helm/autodo/`

**From `chronicle/`:**
- `analyze_sessions.py` → `helm/analyze.py`
- `stats.py` → `helm/stats.py`
- `content_filter.py` → `helm/content_filter.py`
- `native_reader.py` → `helm/native_reader.py` (or just use lib/sessions directly)

### Stays unchanged

- `lib/sessions/` — canonical JSONL reader (shared lib)
- `doctor/` — project health (separate concern)

## Server mapping

| Server | Port | Domain | Project |
|--------|------|--------|---------|
| Watch UI (Gradio) | 7960 | watch.localhost | `watch/` |
| Helm API (FastAPI) | 8130 | helm.api.localhost | `helm/` |

`watch.api.localhost` → renamed to `helm.api.localhost` (keep both as aliases).

## Migration strategy

1. Create `helm/` and `watch/` with new structure
2. Move files, update imports
3. Add backward-compat shims in `supervisor/watch/` and `chronicle/` (thin re-exports)
4. Update Caddy, launchd plists, invoke tasks
5. Verify everything works
6. Remove shims and old directories