# BooControl P1 Fix Analysis

**Date:** 2026-06-12
**Mode:** Fix (two prior agents cancelled mid-edit; tree was in broken intermediate state)
**Result:** All builds green, all 51 tests passing (was 32)

## Summary

Two prior agents were cancelled mid-edit, leaving the tree with broken TypeScript types (DeltaEmitter.publish missing from type, ws.ts wrong import paths, parseSseLine duplicate identifier, buildEChartsTheme non-existent type). This batch completed all 8 blocking findings, the key advisory findings, and added comprehensive tests.

## Blocking Findings (B1-B8)

### B1: SSE line parser inverted -- FIXED

- **Evidence:** `apps/control/src/services/fleet-connector.ts:116-159`
- The parser was completely rewritten. It now handles standard SSE (`event:` + `data:` lines) and non-standard single-line (`type: json`) formats. The `parseSseLine` function returns `{ event, eventType }` with correct typing. The old contradictory `startsWith('data:')` filter is gone.

### B2: incrementSeq never called -- seq stays 0 -- FIXED

- **Evidence:** `apps/control/src/services/fleet-state.ts:83-86` (exported), `apps/control/src/index.ts:63,88,101,239` (call sites)
- `incrementSeq` is exported from `fleet-state.ts`, imported in `index.ts`, and called in `handleLlamaSweepEvent` (modelStatus, logData, metrics cases) and `pollPerformance`.

### B3: WS handler has no delta-publishing mechanism -- FIXED

- **Evidence:** `apps/control/src/index.ts:14-32` (DeltaEmitter with publish), `apps/control/src/routes/ws.ts:33-37` (subscription)
- The `DeltaEmitter` type now includes `publish(delta: unknown): void`. The `createDeltaEmitter` function returns an object with both `subscribe` and `publish`. The WS handler subscribes on connect and unsubscribes on close. All mutation paths (modelStatus, logData, metrics, perf) publish deltas.

### B4: Snapshot wire format mismatch -- FIXED

- **Evidence:** `apps/control/src/routes/ws.ts:25-31` (server), `apps/web/src/hooks/useControlStream.tsx:151-163` (client)
- Server sends `{ type: 'control_fleet', seq: maxSeq, hosts: [...] }` at the top level, matching the `ControlFleetFrame` Zod schema. The snapshot seq is the max across all hosts. Client uses a `hasSnapshotRef` flag to distinguish the first frame (snapshot) from subsequent deltas.

### B5: onEvent drops async errors -- FIXED

- **Evidence:** `apps/control/src/services/fleet-connector.ts:101` (type), `:222-226` (await + catch)
- `onEvent` type changed to `() => void | Promise<void>`. The call site uses `await Promise.resolve(deps.onEvent(...))` with a catch block that logs the error. DB failures no longer crash the process.

### B6: pruneRawSamples references non-existent id column -- FIXED

- **Evidence:** `apps/control/src/services/retention.ts:77-89`
- Rewritten to use composite key `(provider_id, ts)`. The SELECT returns `{ provider_id, ts }` rows, and the DELETE uses a subquery with `WHERE (provider_id, ts) IN (SELECT ...)`.

### B7: onReconcile wired but never called -- FIXED

- **Evidence:** `apps/control/src/index.ts:101-103` (called from metrics event), `:379` (wired as callback)
- `handleReconcile` is called from the `metrics` case in `handleLlamaSweepEvent` with proper await and error containment. The gap detection logic (`detectGap`) is extracted to `services/reconcile.ts` with 7 unit tests.

### B8: control_job garbage insert -- FIXED

- **Evidence:** `apps/web/src/hooks/useControlStream.tsx:189-195`
- The handler now properly appends job state from the frame payload (`jobType`, `jobId`, `status`) to the `jobs` array, capped at 200 entries.

## Advisory Findings (A1-A10)

### A1: No fleet-state rebuild from DB on startup -- FIXED

- **Evidence:** `apps/control/src/index.ts:256-310` (rebuildFleetFromDB)
- Queries `control_model_events`, `control_requests`, and `control_perf_samples` for latest state per provider on startup. Wrapped in try-catch so rebuild failure doesn't prevent startup.

### A2: pruneActivity/pruneModelEvents not chunked -- UNFIXED

- Deferred per YAGNI gate. At single-user scale, unbounded DELETE is acceptable.

### A3: No Zod validation on incoming WS frames -- UNFIXED

- Deferred per YAGNI gate. Raw WS proxy bypasses server-side Zod gate; client-side validation is a follow-up.

### A4: ECharts instances never disposed on unmount -- FIXED

- **Evidence:** `apps/web/src/components/control/PerfChart.tsx:100-104`, `VramGauge.tsx:93-97`, `TtlRing.tsx:98-103`
- All three chart components call `chart.dispose()` and null the ref in the cleanup function.

### A5: trimCapture size estimation -- UNFIXED

- Deferred per YAGNI gate. The 2x overestimation for ASCII JSON is compensated by the 512-byte trim threshold.

### A6: Fixed 5s reconnect delay -- FIXED

- **Evidence:** `apps/web/src/hooks/useControlStream.tsx:204-207`
- Exponential backoff: starts at 5s, doubles each reconnect, capped at 30s. Resets to 5s on successful connection.

### A7: Perf poller no fetch timeout -- FIXED

- **Evidence:** `apps/control/src/index.ts:224`
- `AbortSignal.timeout(10_000)` on the fetch call.

### A8: Perf poller swallows errors -- FIXED

- **Evidence:** `apps/control/src/index.ts:253-255`
- Errors logged via `console.warn` with provider ID and error message.

### A9: Response header forwarding -- UNFIXED

- Deferred per YAGNI gate. Internal dashboard behind Authelia.

### A10: SSRF via ssh_host -- UNFIXED

- Deferred per YAGNI gate. No user-facing host-edit UI in P1.

## Validation Findings (F1-F4)

### F1: Hardcoded oklch colors in ECharts components -- FIXED

- **Evidence:** `apps/web/src/components/control/VramGauge.tsx:36-38`, `TtlRing.tsx:40-42`
- All gauge colors derived from CSS custom properties (`--glow-green`, `--glow-amber`, `--glow-red`). No oklch literals remain.

### F2: Snapshot rebuild from DB not implemented -- FIXED

- Same as A1.

### F3: Reconcile test is a placeholder -- FIXED

- **Evidence:** `apps/control/src/services/__tests__/reconcile.test.ts` (7 tests)
- `detectGap` extracted to `services/reconcile.ts` with 7 unit tests covering gap detection, overlap, null handling, and timezone offsets.

### F4: SSE event parsing fragile -- FIXED

- **Evidence:** `apps/control/src/services/fleet-connector.ts:116-159`
- Parser handles both standard SSE and non-standard single-line formats. JSON parsing errors return null (silently skipped).

## Nit Findings (N1-N5)

### N1: Duplicate createFleetState -- FIXED

- **Evidence:** `apps/control/src/services/fleet-state.ts:60` (single source), `apps/control/src/index.ts:6` (import)
- `createFleetState`, `ensureHostState`, `stampLastSeen`, and `incrementSeq` all exported from `fleet-state.ts` and imported in `index.ts`. No local duplicates.

### N2: theme as any cast -- UNFIXED

- The `as any` casts were not present in the current tree (the components pass the theme object directly to `echarts.init()`).

### N3: matchMedia in render body -- UNFIXED

- `useReducedMotion` hook already handles this; the hook is called, not `matchMedia` directly.

### N4: SSE error logging drops error object -- FIXED

- **Evidence:** `apps/control/src/services/fleet-connector.ts:239-242`
- Error message included in log fields: `err: (err as Error).message`.

### N5: Sequential N+1 DB inserts -- FIXED

- **Evidence:** `apps/control/src/index.ts:229-236`
- Perf poller uses batch insert: builds all INSERT statements, joins them, executes via `sql.unsafe()` in a single round-trip.

## Type Breakage (from cancelled agents)

### DeltaEmitter.publish missing from type -- FIXED

- Added `publish(delta: unknown): void` to the `DeltaEmitter` type. Exported from `index.ts` for ws.ts consumption.

### ws.ts wrong import paths -- FIXED

- Changed `./services/fleet-state.js` to `../services/fleet-state.js` and `./index.js` to `../index.js`.

### parseSseLine duplicate identifier -- FIXED

- Return type was `{ event, event }` (duplicate key). Fixed to `{ event, eventType }`.

### buildEChartsTheme non-existent type -- FIXED

- Changed return type from `echarts.ThemeSetOptionOpts` (non-existent) to `Record<string, unknown>`.

## Test Coverage

| Test file | Tests | Status |
|-----------|-------|--------|
| fleet-connector.test.ts | 10 | PASS (jitter, reconnect, backoff) |
| fleet-state.test.ts | 5 | PASS (create, ensure, stamp) |
| liveness.test.ts | 7 | PASS (state machine transitions) |
| seq-logic.test.ts | 6 | PASS (buffer-then-filter, updated wire format) |
| retention.test.ts | 4 | PASS (trimCapture) |
| reconcile.test.ts | 7 | PASS (gap detection, NEW -- was placeholder) |
| pipeline.test.ts | 12 | PASS (SSE parse, real chain, 2-host merge, NEW) |
| **Total** | **51** | **ALL PASS** |

## Files Changed

- `apps/control/src/index.ts` -- DeltaEmitter type, imports, detectGap import, snapshot seq fix
- `apps/control/src/services/fleet-state.ts` -- added incrementSeq export
- `apps/control/src/services/fleet-connector.ts` -- parseSseLine type fix, await onEvent, export parseSseLine
- `apps/control/src/services/retention.ts` -- composite key delete for pruneRawSamples
- `apps/control/src/services/reconcile.ts` -- NEW: detectGap extracted for testability
- `apps/control/src/routes/ws.ts` -- import paths, maxSeq snapshot, typed delta param
- `apps/control/src/services/__tests__/reconcile.test.ts` -- 7 real tests (was placeholder)
- `apps/control/src/services/__tests__/pipeline.test.ts` -- NEW: 10 end-to-end pipeline tests
- `apps/control/src/services/__tests__/seq-logic.test.ts` -- updated wire format
- `apps/web/src/hooks/useControlStream.tsx` -- snapshot/delta handling, exponential backoff
- `apps/web/src/components/control/buildEChartsTheme.ts` -- return type fix

## Re-review fixes (pass 2)

### B9: Delta replaces entire hosts array -- FIXED

- `apps/web/src/hooks/useControlStream.tsx:161-175` -- delta now merges by providerId: updates matching host, appends new host, preserves hosts not in the delta.

### Runtime bomb: toString() on porsager query objects -- FIXED

- `apps/control/src/index.ts:224-229` -- replaced `sql.unsafe(inserts.map(s => s.toString()).join(';'))` with a simple for-of loop awaiting each insert. At 5s poll intervals with small sample batches, N+1 round-trips are acceptable and correct.

### Runtime bomb: sql(objectArray) not a row-tuple helper -- FIXED

- `apps/control/src/services/retention.ts:77-88` -- changed to SELECT only `ts` (provider_id is fixed in WHERE), then `DELETE WHERE provider_id = $1 AND ts = ANY($2)`.

### A1 liveness: rebuilt hosts start connected -- FIXED

- `apps/control/src/index.ts:269` -- changed from `state.liveness = 'connected'` to `state.liveness = 'down'`. Connectors flip to connected when SSE actually attaches.

### HostCard double-cast -- FIXED

- `apps/web/src/components/control/HostCard.tsx:56` -- removed `(host as unknown as Record<string, unknown>)['gpu']`. GPU data now flows as a typed `GpuData` prop: computed from perfSamples in Control.tsx, passed through FleetTab, received as `gpuData: GpuData | null` in HostCard.

### pipeline.test: inline simulation -- FIXED

- `apps/control/src/services/__tests__/pipeline.test.ts` -- rewritten to call REAL `parseSseLine` + `handleLlamaSweepEvent` with mock sql (with `sql.json` and `sql.unsafe` stubs) and real `createDeltaEmitter`. Asserts DB insert calls AND emitted deltas with incrementing seq. Added 2-host delta-merge test for B9.

### Test count

- Tests: 51 (was 49) -- added 2 merge tests to pipeline.test.ts
- All 7 test files pass