Architecture: session.ts god class (1341 lines, 6+ concerns)

[OneStepAt4time]

Summary

SessionManager handles session CRUD, tmux window lifecycle, permission guard, hook settings, JSONL discovery (two algorithms), permission resolution, question answering, transcript reading, health checks, state persistence, latency metrics, subagent tracking, and session map cleanup.

Details

• File: src/session.ts (1341 lines)
• Severity: High
• No schema validation on state.json load — corrupted JSON silently resets all sessions
• No cleanup on tmux createWindow failure — permission guard + hook settings left orphaned on disk
• reconcile() window liveness uses OR (windowId || windowName) — too permissive for tmux ID reuse
• save() called on every API read (excessive disk I/O for read-heavy patterns)
• Race condition: concurrent createSession and killSession can resurrect deleted sessions
• session_map.json read/written by 3 methods with no write coordination (no queue)
• activeSubagents uses array with O(n) operations — should be Set
• Discovery timeout handles leak (not cleared on session kill)
• Case sensitivity inconsistency between reconcile() and purgeStaleSessionMapEntries()
• readMessages and readMessagesForMonitor silently swallow JSONL read errors

Suggested Fix

Extract into focused classes:

• SessionDiscovery (~190 lines) — session_map.json + filesystem scanning
• PermissionGateway (~155 lines) — pending permission/question resolution
• StateStore (~60 lines) — persistence with write queue
• Add schema validation on state.json load (Zod or manual checks)
• Wrap createWindow in try/catch with cleanup on failure
• Use AND for window liveness check
• Debounce save() for offset-only changes

[OneStepAt4time]

Resuming milestone execution after urgent interrupt.

Starting #351 as next active slot (session.ts decomposition).
Immediate plan:

1. map cohesive boundaries in session lifecycle
2. extract first low-risk module with behavior-preserving tests
3. open incremental PR (phase 1) to reduce god-class surface safely

[OneStepAt4time]

Phase-1 decomposition is in PR #988.

Implemented:

• extracted pending permission request lifecycle from session.ts into permission-request-manager.ts
• kept SessionManager public API stable through delegation

Validation:

• focused permission regression suite passed
• npx tsc --noEmit passed

Next planned #351 step:

• extract pending question lifecycle with same pattern to further shrink session.ts responsibilities.