docs(19): create phase plan for memory leak audit

Phase 19: Audit and Discovery - 1 plan in 1 wave - 3 tasks covering VU meters, chat, session screen - Produces 19-AUDIT.md with prioritized findings for Phases 20-22 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-08 14:10:35 +05:30 · 2026-02-08 14:10:35 +05:30 · c466a72511
parent a66cbdca92
commit c466a72511
2 changed files with 279 additions and 4 deletions
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@ -385,9 +385,9 @@ Plans:
 #### Phase 19: Audit and Discovery
 **Goal**: Investigate all three areas (VU meters, chat, session screen) and identify actual memory leaks with evidence
 **Depends on**: Phase 18 (previous milestone complete)
-**Research**: Likely (code audit to identify actual leak sources)
+**Research**: Complete (19-RESEARCH.md)
 **Requirements**: None (discovery phase - informs subsequent phases)
-**Plans**: TBD (1-2 plans expected)
+**Plans**: 1 plan

 **Success Criteria:**
 1. VU meter components audited - all setInterval, setTimeout, and requestAnimationFrame calls documented
@ -397,7 +397,7 @@ Plans:
 5. Priority ranking of fixes based on severity (which leaks cause the 10-minute freeze)

 Plans:
- [ ] 19-01: TBD
+- [ ] 19-01-PLAN.md — Comprehensive memory leak audit (VU meters, chat, session screen)

 #### Phase 20: VU Meter Fixes
 **Goal**: Fix identified VU meter interval/animation cleanup issues
@ -493,7 +493,7 @@ Phases execute in numeric order: 1 → 2 → ... → 18 → 19 → 20 → 21 →
 | 16. Attachment Finalization | v1.2 | 2/2 | Complete | 2026-02-07 |
 | 17. Unit Tests (Jest) | v1.3 | 1/1 | Complete | 2026-02-08 |
 | 18. Integration Tests (Playwright) | v1.3 | 1/1 | Complete | 2026-02-08 |
-| 19. Audit and Discovery | v1.4 | 0/TBD | Not started | - |
+| 19. Audit and Discovery | v1.4 | 0/1 | Not started | - |
 | 20. VU Meter Fixes | v1.4 | 0/TBD | Not started | - |
 | 21. Chat Window Fixes | v1.4 | 0/TBD | Not started | - |
 | 22. Session Screen Fixes | v1.4 | 0/TBD | Not started | - |
--- a/.planning/phases/19-audit-and-discovery/19-01-PLAN.md
+++ b/.planning/phases/19-audit-and-discovery/19-01-PLAN.md
@ -0,0 +1,275 @@
+---
+phase: 19-audit-and-discovery
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - .planning/phases/19-audit-and-discovery/19-AUDIT.md
+autonomous: true
+
+must_haves:
+  truths:
+    - "VU meter components audited with all timer/animation calls documented"
+    - "Chat components audited with WebSocket and state growth patterns documented"
+    - "Session screen components audited with all useEffect hooks documented"
+    - "Leak sources identified with severity ratings and evidence"
+    - "Priority ranking exists for Phases 20-22 implementation"
+  artifacts:
+    - path: ".planning/phases/19-audit-and-discovery/19-AUDIT.md"
+      provides: "Comprehensive memory leak audit report"
+      contains: "## VU Meter Audit"
+    - path: ".planning/phases/19-audit-and-discovery/19-AUDIT.md"
+      provides: "Comprehensive memory leak audit report"
+      contains: "## Chat Window Audit"
+    - path: ".planning/phases/19-audit-and-discovery/19-AUDIT.md"
+      provides: "Comprehensive memory leak audit report"
+      contains: "## Session Screen Audit"
+  key_links:
+    - from: "19-AUDIT.md"
+      to: "Phase 20 (VU Meter Fixes)"
+      via: "Priority findings inform implementation"
+      pattern: "VUMTR-"
+    - from: "19-AUDIT.md"
+      to: "Phase 21 (Chat Fixes)"
+      via: "Priority findings inform implementation"
+      pattern: "CHAT-"
+    - from: "19-AUDIT.md"
+      to: "Phase 22 (Session Screen Fixes)"
+      via: "Priority findings inform implementation"
+      pattern: "SESS-"
+---
+
+<objective>
+Systematically audit the session screen codebase to identify memory leaks causing the ~10-minute session freeze. Document all findings with evidence (file paths, line numbers, severity) and create a prioritized fix list for subsequent phases.
+
+Purpose: Enable confident, targeted fixes in Phases 20-22 by providing evidence-based audit findings rather than guesswork.
+
+Output: `19-AUDIT.md` containing comprehensive audit findings for VU meters, chat window, and session screen components with severity ratings and implementation recommendations.
+</objective>
+
+<execution_context>
+@/Users/nuwan/.claude/get-shit-done/workflows/execute-plan.md
+@/Users/nuwan/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/19-audit-and-discovery/19-RESEARCH.md
+
+# Primary audit targets (from research)
+@jam-ui/src/components/client/JKSessionScreen.js
+@jam-ui/src/components/client/SessionTrackVU.js
+@jam-ui/src/components/client/JKSessionChatWindow.js
+@jam-ui/src/components/client/chat/JKChatMessageList.js
+@jam-ui/src/components/client/JKSessionBackingTrackPlayer.js
+@jam-ui/src/components/client/JKSessionJamTrackPlayer.js
+
+# Supporting hooks
+@jam-ui/src/hooks/useJamServer.js
+@jam-ui/src/hooks/useMixerStore.js
+@jam-ui/src/hooks/useVuHelpers.js
+@jam-ui/src/hooks/useSessionStats.js
+@jam-ui/src/hooks/useSessionModel.js
+@jam-ui/src/hooks/useSessionWebSocket.js
+
+# Redux slices
+@jam-ui/src/store/features/sessionChatSlice.js
+@jam-ui/src/store/features/mixersSlice.js
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Audit VU Meter Components</name>
+  <files>.planning/phases/19-audit-and-discovery/19-AUDIT.md (partial)</files>
+  <action>
+Audit VU meter-related files for memory leak patterns. For each file, document:
+1. All `setInterval`, `setTimeout`, `requestAnimationFrame` calls with line numbers
+2. Whether each has a corresponding cleanup (clearInterval, clearTimeout, cancelAnimationFrame)
+3. All `window.addEventListener` or `window.JK.*` callback registrations
+4. Whether callbacks are properly unregistered on cleanup
+
+**Files to audit:**
+- `jam-ui/src/components/client/SessionTrackVU.js` - VU meter visualization component
+- `jam-ui/src/hooks/useMixerStore.js` - window.JK.HandleBridgeCallback2 registration
+- `jam-ui/src/hooks/useVuHelpers.js` - VuStates accumulation patterns
+- `jam-ui/src/context/VuContext.js` - VU context provider
+
+**Verification patterns to grep:**
+```bash
+grep -n "setInterval\|setTimeout\|requestAnimationFrame" jam-ui/src/components/client/SessionTrackVU.js
+grep -n "clearInterval\|clearTimeout\|cancelAnimationFrame" jam-ui/src/components/client/SessionTrackVU.js
+grep -n "window\.JK\|HandleBridgeCallback" jam-ui/src/hooks/useMixerStore.js
+grep -n "return.*=>" jam-ui/src/hooks/useVuHelpers.js  # cleanup returns
+```
+
+**Document findings** in the VU Meter Audit section with:
+- File path and line numbers
+- Pattern found (timer, callback, etc.)
+- Has cleanup: YES/NO/PARTIAL
+- Severity: HIGH/MEDIUM/LOW
+- Notes: Specific concerns or edge cases
+
+**Requirements coverage:** VUMTR-01, VUMTR-02, VUMTR-03
+  </action>
+  <verify>
+Grep confirms all timer/animation patterns documented:
+```bash
+# Verify all setInterval/setTimeout/requestAnimationFrame calls are in audit
+grep -c "setInterval\|setTimeout\|requestAnimationFrame" jam-ui/src/components/client/SessionTrackVU.js jam-ui/src/hooks/useMixerStore.js jam-ui/src/hooks/useVuHelpers.js
+```
+Each count should have corresponding entry in 19-AUDIT.md VU Meter section.
+  </verify>
+  <done>
+VU meter audit section complete with:
+- All timer/animation calls documented with line numbers
+- Cleanup status verified (YES/NO/PARTIAL)
+- Severity ratings assigned
+- VUMTR-01, VUMTR-02, VUMTR-03 coverage confirmed
+  </done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Audit Chat Window Components</name>
+  <files>.planning/phases/19-audit-and-discovery/19-AUDIT.md (partial)</files>
+  <action>
+Audit chat-related files for memory leak patterns. For each file, document:
+1. WebSocket listener registration and cleanup patterns
+2. Redux state growth patterns (especially messagesByChannel)
+3. Event listeners and their cleanup
+4. Any setTimeout/setInterval calls
+
+**Files to audit:**
+- `jam-ui/src/components/client/JKSessionChatWindow.js` - Chat window container
+- `jam-ui/src/components/client/chat/JKChatMessageList.js` - Message list with scroll
+- `jam-ui/src/store/features/sessionChatSlice.js` - Redux state for messages
+- `jam-ui/src/hooks/useSessionWebSocket.js` - WebSocket callback handling
+
+**Critical check for sessionChatSlice.js:**
+- Search for message array manipulation: `push`, `concat`, `spread [...messages]`
+- Check if there's a max message limit
+- Document if messages accumulate unbounded
+
+**Verification patterns:**
+```bash
+grep -n "addEventListener\|removeEventListener" jam-ui/src/components/client/JKSessionChatWindow.js
+grep -n "setTimeout\|clearTimeout" jam-ui/src/components/client/chat/JKChatMessageList.js
+grep -n "messagesByChannel\|\.push\|concat" jam-ui/src/store/features/sessionChatSlice.js
+grep -n "registerMessageCallback\|unregisterMessageCallback" jam-ui/src/hooks/useSessionWebSocket.js
+```
+
+**Document findings** in the Chat Window Audit section with:
+- File path and line numbers
+- Pattern found
+- Has cleanup: YES/NO/PARTIAL
+- Severity: HIGH/MEDIUM/LOW (unbounded growth = HIGH)
+- Notes: Specific concerns or edge cases
+
+**Requirements coverage:** CHAT-01, CHAT-02, CHAT-03
+  </action>
+  <verify>
+Grep confirms all listener/callback patterns documented:
+```bash
+grep -c "addEventListener\|setTimeout\|registerMessageCallback" jam-ui/src/components/client/JKSessionChatWindow.js jam-ui/src/components/client/chat/JKChatMessageList.js jam-ui/src/hooks/useSessionWebSocket.js
+```
+Each count should have corresponding entry in 19-AUDIT.md Chat Window section.
+  </verify>
+  <done>
+Chat window audit section complete with:
+- WebSocket callback patterns documented
+- Message state growth analyzed (bounded/unbounded)
+- Event listener cleanup verified
+- CHAT-01, CHAT-02, CHAT-03 coverage confirmed
+  </done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Audit Session Screen and Finalize Report</name>
+  <files>.planning/phases/19-audit-and-discovery/19-AUDIT.md</files>
+  <action>
+Audit session screen and supporting hooks for memory leak patterns. Then consolidate all findings into prioritized recommendations.
+
+**Files to audit:**
+- `jam-ui/src/components/client/JKSessionScreen.js` - Main session component
+- `jam-ui/src/hooks/useJamServer.js` - WebSocket connection and heartbeat
+- `jam-ui/src/hooks/useSessionStats.js` - Stats polling
+- `jam-ui/src/hooks/useSessionModel.js` - Session model with timers
+- `jam-ui/src/components/client/JKSessionBackingTrackPlayer.js` - Playback polling
+- `jam-ui/src/components/client/JKSessionJamTrackPlayer.js` - JamTrack polling
+
+**For JKSessionScreen.js specifically:**
+- Document all useEffect hooks (count total, count with cleanup returns)
+- List all callback registrations stored in state
+- Verify all exit paths (leave, error, timeout) trigger cleanup
+
+**Verification patterns:**
+```bash
+grep -n "useEffect" jam-ui/src/components/client/JKSessionScreen.js | wc -l
+grep -n "return.*=>" jam-ui/src/components/client/JKSessionScreen.js  # cleanup returns
+grep -n "setInterval\|setTimeout" jam-ui/src/hooks/useJamServer.js jam-ui/src/hooks/useSessionStats.js
+grep -n "clearInterval\|clearTimeout" jam-ui/src/hooks/useJamServer.js jam-ui/src/hooks/useSessionStats.js
+```
+
+**Document findings** in the Session Screen Audit section.
+
+**Then create Priority Summary:**
+1. List all HIGH severity findings (these likely cause the 10-minute freeze)
+2. List MEDIUM severity findings (contribute to degradation)
+3. List LOW severity findings (minor, but fix for completeness)
+
+**Create Implementation Recommendations:**
+- Phase 20 tasks (VU meter fixes) based on VUMTR findings
+- Phase 21 tasks (Chat fixes) based on CHAT findings
+- Phase 22 tasks (Session screen fixes) based on SESS findings
+
+**Requirements coverage:** SESS-01, SESS-02, SESS-03
+  </action>
+  <verify>
+Complete audit report exists:
+```bash
+# Verify all sections present
+grep -E "^## VU Meter Audit|^## Chat Window Audit|^## Session Screen Audit|^## Priority Summary|^## Implementation Recommendations" .planning/phases/19-audit-and-discovery/19-AUDIT.md
+```
+Should return 5 section headers.
+
+```bash
+# Verify severity ratings present
+grep -c "HIGH\|MEDIUM\|LOW" .planning/phases/19-audit-and-discovery/19-AUDIT.md
+```
+Should return count > 10 (multiple findings with ratings).
+  </verify>
+  <done>
+Complete 19-AUDIT.md with:
+- VU Meter Audit section (VUMTR-01, VUMTR-02, VUMTR-03)
+- Chat Window Audit section (CHAT-01, CHAT-02, CHAT-03)
+- Session Screen Audit section (SESS-01, SESS-02, SESS-03)
+- Priority Summary with HIGH/MEDIUM/LOW rankings
+- Implementation Recommendations for Phases 20-22
+  </done>
+</task>
+
+</tasks>
+
+<verification>
+1. All three audit sections complete with file/line references
+2. Every timer/callback pattern has cleanup status documented
+3. Severity ratings assigned to each finding
+4. Priority summary identifies likely causes of 10-minute freeze
+5. Implementation recommendations map to Phases 20-22
+</verification>
+
+<success_criteria>
+1. `19-AUDIT.md` exists with all required sections
+2. VU meter audit covers VUMTR-01, VUMTR-02, VUMTR-03
+3. Chat audit covers CHAT-01, CHAT-02, CHAT-03
+4. Session screen audit covers SESS-01, SESS-02, SESS-03
+5. Priority ranking identifies HIGH severity leaks as primary fix targets
+6. Report provides clear implementation guidance for Phases 20-22
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/19-audit-and-discovery/19-01-SUMMARY.md`
+</output>