ai-agent-session-center 2.0.2 → 2.0.3

package/docs/ERROR_185_ANALYSIS.md

@@ -0,0 +1,263 @@
+# React Error #185: Complete Architecture Analysis
+
+> **Error**: "Maximum update depth exceeded" when clicking a 3D robot to open session detail panel.
+> **Impact**: Crashes the WebGL context (`THREE.WebGLRenderer: Context Lost`), requires page reload.
+
+---
+
+## 1. What is React Error #185?
+
+React Error #185 fires when a component triggers a state update during rendering, which triggers another render, which triggers another update — an infinite `setState → render → setState` loop. React detects this after ~50 nested updates and throws.
+
+---
+
+## 2. Current Click-to-Detail Architecture
+
+### Component Tree
+
+```
+App.tsx (React DOM root)
+├── AppLayout
+│   ├── Header, NavBar, ActivityFeed (React DOM)
+│   ├── <LiveView /> → <CyberdromeScene />
+│   │   ├── <Canvas>  ← R3F RECONCILER BOUNDARY
+│   │   │   ├── SceneContent
+│   │   │   │   ├── SessionRobot ×N (memo'd)
+│   │   │   │   │   ├── Robot3DModel (pure Three.js meshes)
+│   │   │   │   │   ├── RobotLabel (drei <Text> + <Billboard>)
+│   │   │   │   │   ├── RobotDialogue (drei <Text> + <Billboard>)
+│   │   │   │   │   └── StatusParticles (Three.js Points)
+│   │   │   │   ├── SubagentConnections (Three.js Lines)
+│   │   │   │   └── CyberdromeEnvironment (Three.js meshes)
+│   │   │   ├── CameraController
+│   │   │   └── OrbitControls
+│   │   ├── MapControls (DOM overlay, outside Canvas)
+│   │   ├── SceneOverlay (DOM overlay, outside Canvas)
+│   │   └── RobotListSidebar (DOM overlay, outside Canvas)
+│   ├── DetailPanel ← OUTSIDE Canvas, subscribes to selectedSessionId
+│   ├── SettingsPanel
+│   └── Modals (Kill, Alert, Summarize)
+```
+
+### The Click Flow
+
+```
+1. User clicks robot mesh
+     ↓
+2. R3F raycasts and fires onClick on <group> in SessionRobot
+     ↓
+3. handleClick: setTimeout(() => onSelect(session.sessionId), 0)
+     ↓ (deferred to next event loop tick)
+4. onSelect = handleSelect in SceneContent:
+     a. selectSession(sessionId)   → updates sessionStore.selectedSessionId
+     b. flyTo(pos, lookAt)         → updates cameraStore.animation
+     ↓
+5. Zustand notifies ALL subscribers synchronously:
+     ↓
+   SUBSCRIBERS TO selectedSessionId (sessionStore):
+     a. DetailPanel (React DOM)       → re-renders, shows slide-in panel
+     b. RobotListSidebar (React DOM)  → re-renders, highlights selected entry
+     c. SummarizeModal (React DOM)    → conditional re-render
+     d. KillConfirmModal (React DOM)  → conditional re-render
+     e. AlertModal (React DOM)        → conditional re-render
+     f. useKeyboardShortcuts hook     → no visual re-render
+
+   SUBSCRIBERS TO sessions (sessionStore):
+     a. SceneContent (R3F)            → NOT triggered (sessions Map unchanged)
+     b. SubagentConnections (R3F)     → NOT triggered (sessions Map unchanged)
+     c. RobotListSidebar (React DOM)  → also subscribes to sessions
+
+   SUBSCRIBERS TO animation (cameraStore):
+     a. CameraController (R3F)        → triggers useFrame lerp animation
+```
+
+### The Dual-Reconciler Problem
+
+React Three Fiber maintains its OWN React reconciler separate from React DOM's reconciler. Both share the same React runtime. When a Zustand store update fires:
+
+1. **React DOM reconciler** processes subscribers (DetailPanel, RobotListSidebar, modals)
+2. **R3F reconciler** processes subscribers (SceneContent, CameraController)
+
+These two reconcilers can **interleave** — one reconciler's flush can trigger effects that cause the other to flush, creating a ping-pong cascade.
+
+---
+
+## 3. Why Previous Fixes Failed
+
+### Fix Attempt 1: `startTransition(() => onSelect(...))`
+**Why it failed**: `startTransition` defers the update within ONE reconciler, but doesn't prevent cross-reconciler cascades. React DOM's deferred update can still trigger R3F's reconciler to flush synchronously.
+
+### Fix Attempt 2: `setTimeout(() => onSelect(...), 0)`
+**Why it partially works**: Moves the store update completely out of R3F's render loop. But the problem persists because:
+- The `setTimeout` fires and calls `selectSession(sessionId)` + `flyTo()`
+- `selectSession` synchronously notifies Zustand subscribers
+- DetailPanel (React DOM) re-renders → mounts heavy child components
+- R3F's animation frame may be processing simultaneously
+- If any R3F component also triggers a state update (even indirectly), cascade begins
+
+### Fix Attempt 3: `memo(SessionRobot)` with granular comparator
+**Why it helps but isn't sufficient**: Prevents SessionRobots from re-rendering when `sessions` Map gets a new reference but their specific session data hasn't changed. However, the `sessions` Map reference doesn't change on `selectSession` (only `selectedSessionId` changes), so this memo was never the actual trigger.
+
+### Fix Attempt 4: `seatedRef` / `isHoveredRef` / `dialogueRef`
+**Why it helps but isn't the root cause**: Eliminates all `useState` from SessionRobot's render cycle. No React state updates happen inside R3F's tree from these refs. Good defensive measure, but the crash still happens because the problem is in the cross-reconciler interaction triggered by Zustand, not by local state.
+
+---
+
+## 4. Root Cause: The Zustand Cross-Reconciler Bridge
+
+The **fundamental** problem is:
+
+```
+sessionStore.selectSession(id)
+  → Zustand.setState({ selectedSessionId: id })
+  → Zustand notifies ALL subscribers SYNCHRONOUSLY
+  → React DOM subscribers (DetailPanel) flush
+  → React DOM flush may trigger layout effects
+  → R3F's next frame picks up any pending work
+  → If any R3F component has pending effects → cascade
+```
+
+Specifically, when Zustand notifies subscribers, it calls `useSyncExternalStore` in both reconcilers. React 19's concurrent features mean the DOM reconciler may start a render that the R3F reconciler then sees as a pending update.
+
+### The Dangerous Components Inside R3F's Canvas
+
+Even after all fixes, these components inside `<Canvas>` still subscribe to Zustand stores:
+
+| Component | Store | Selector | Risk |
+|-----------|-------|----------|------|
+| SceneContent | sessionStore | `s.sessions` | Medium — triggers on any session update |
+| SceneContent | sessionStore | `s.selectSession` | Low — stable fn ref |
+| SceneContent | cameraStore | `s.flyTo` | Low — stable fn ref |
+| SubagentConnections | sessionStore | `s.sessions` | Medium — triggers on any session update |
+| Robot3DModel | settingsStore | `s.animationIntensity` | Low |
+| Robot3DModel | settingsStore | `s.animationSpeed` | Low |
+| SessionRobot | roomStore | `s.getRoomForSession` | Low — stable fn ref |
+| SessionRobot | settingsStore | `s.characterModel` | Low |
+| SessionRobot | settingsStore | `s.labelSettings` | Low |
+| CameraController | cameraStore | `s.animation` | **HIGH — triggers on flyTo()** |
+| SceneThemeSync | settingsStore | `s.themeName` | Low |
+
+**CameraController** is the likely remaining trigger. When `handleSelect` calls `flyTo()`, CameraController re-renders because `s.animation` changes. This re-render happens **inside R3F's reconciler** at the same time that DetailPanel is re-rendering in React DOM's reconciler.
+
+---
+
+## 5. The Remaining Hazard: `SubagentConnections`
+
+`SubagentConnections` subscribes to `useSessionStore((s) => s.sessions)`. While `selectSession` doesn't change `sessions`, the `updateSession` action (from WebSocket) creates a new `Map` reference every time. If a WebSocket update arrives at the exact moment the click handler fires, SubagentConnections re-renders inside R3F while DetailPanel re-renders in DOM — cross-reconciler cascade.
+
+---
+
+## 6. Solution: Decouple the Two Reconcilers Completely
+
+The only reliable fix is to ensure **NO shared reactive state** bridges the R3F and DOM reconcilers. The R3F tree should read data imperatively (via refs or callbacks), never via Zustand subscriptions that can trigger simultaneous re-renders.
+
+### Option A: Event-Based Communication (Recommended)
+
+Replace the Zustand `selectedSessionId` bridge with a custom event:
+
+```
+Robot click → dispatch CustomEvent('select-session', { sessionId })
+              ↓
+DOM listener (outside Canvas) → updates local React state
+              ↓
+DetailPanel renders from local state (never touches R3F)
+```
+
+R3F components never subscribe to `selectedSessionId`. The click handler dispatches a DOM event. A DOM-only listener (in CyberdromeScene's wrapper or App) catches it and calls `selectSession`. This ensures:
+
+- R3F's reconciler has ZERO work to do when a session is selected
+- React DOM's reconciler handles DetailPanel independently
+- No cross-reconciler flush interleaving
+
+### Option B: Ref-Based Bridge
+
+Store `selectedSessionId` in a `useRef` at the Canvas boundary. R3F reads it imperatively in `useFrame`. DOM components use the normal Zustand subscription. No R3F component subscribes to `selectedSessionId`.
+
+### Option C: Move ALL Zustand Subscriptions Outside Canvas
+
+Move `SceneContent` and `SubagentConnections` to read sessions via a ref that's updated outside Canvas. Pass session data as props computed in the DOM layer. This eliminates all Zustand subscriptions from inside `<Canvas>`.
+
+---
+
+## 7. Additional Hazards to Fix
+
+### A. `SubagentConnections` sessions subscription
+Subscribes to `s.sessions` inside Canvas. Every WebSocket `updateSession` creates a new Map, causing re-render. Should use a ref or compute connections outside Canvas.
+
+### B. `SceneContent` sessions subscription
+Same issue — `useSessionStore((s) => s.sessions)` re-renders SceneContent on every session update. Should receive sessions as a prop from outside Canvas, or use a ref.
+
+### C. `Robot3DModel` settingsStore subscriptions
+`animationIntensity` and `animationSpeed` subscriptions cause Robot3DModel to re-render when settings change. Should read via `useSettingsStore.getState()` inside useFrame instead of subscribing.
+
+### D. `CameraController` cameraStore subscription
+Re-renders when `flyTo()` is called. The animation data should be read via ref in useFrame, not via subscription.
+
+### E. `RobotListSidebar` calls `selectSession` directly
+Line 202: `selectSession(sessionId)` — this DOM component calls the same function that triggers the cross-reconciler cascade. Should use the same decoupled mechanism as the robot click.
+
+---
+
+## 8. Files Involved
+
+| File | Role | Issues |
+|------|------|--------|
+| `src/App.tsx:53` | Mounts `<DetailPanel />` | None — correct placement outside Canvas |
+| `src/routes/LiveView.tsx` | Wraps `<CyberdromeScene />` | None |
+| `src/components/3d/CyberdromeScene.tsx:89-103` | `SceneContent` subscribes to `sessions` + calls `selectSession` + `flyTo` | **PRIMARY ISSUE**: Zustand subscriptions inside Canvas |
+| `src/components/3d/CyberdromeScene.tsx:74-130` | `SceneContent` function | Sessions subscription triggers re-render |
+| `src/components/3d/SessionRobot.tsx:431-438` | `handleClick` with setTimeout | Good fix but insufficient |
+| `src/components/3d/SessionRobot.tsx:668-692` | `memo` wrapper | Good but sessions Map ref unchanged on select |
+| `src/components/3d/Robot3DModel.tsx:100-102` | Settings subscriptions | Should use getState() in useFrame |
+| `src/components/3d/RobotLabel.tsx` | Pure WebGL (drei Text) | **SAFE** — no Html portals, no store subscriptions |
+| `src/components/3d/RobotDialogue.tsx` | Pure WebGL (drei Text) | **SAFE** — ref-based, no store subscriptions |
+| `src/components/3d/SubagentConnections.tsx:89` | `sessions` subscription | **DANGEROUS** — re-renders inside Canvas on every session update |
+| `src/components/3d/CameraController.tsx` | `animation` subscription | **DANGEROUS** — re-renders inside Canvas on flyTo |
+| `src/components/session/DetailPanel.tsx:68` | `selectedSessionId` subscription | Fine — outside Canvas |
+| `src/components/3d/RobotListSidebar.tsx:180-183` | Multiple store subscriptions | Fine — outside Canvas (DOM overlay) |
+| `src/stores/sessionStore.ts:56` | `selectSession` action | Triggers all subscribers synchronously |
+| `src/stores/cameraStore.ts` | `flyTo` action | Triggers CameraController re-render inside Canvas |
+
+---
+
+## 9. Recommended Redevelopment Plan
+
+### Phase 1: Eliminate ALL Zustand subscriptions from inside `<Canvas>`
+
+1. **SceneContent**: Remove `useSessionStore` and `useCameraStore` subscriptions. Receive `sessions`, `selectSession`, `flyTo` as props from CyberdromeScene (DOM layer).
+
+2. **SubagentConnections**: Remove `useSessionStore` subscription. Receive `sessions` or precomputed connections as props.
+
+3. **Robot3DModel**: Replace `useSettingsStore` subscriptions with `useSettingsStore.getState()` reads inside useFrame.
+
+4. **CameraController**: Replace `useCameraStore((s) => s.animation)` subscription with polling in useFrame via `useCameraStore.getState()`.
+
+5. **SceneThemeSync**: Replace `useSettingsStore` subscription with receiving theme as a prop.
+
+### Phase 2: Replace cross-reconciler selection bridge
+
+1. Robot click dispatches `window.dispatchEvent(new CustomEvent('robot-select', { detail: { sessionId } }))`.
+
+2. CyberdromeScene (DOM wrapper) listens for 'robot-select' and calls `selectSession()` + `flyTo()`.
+
+3. RobotListSidebar dispatches same event instead of calling `selectSession()` directly.
+
+4. DetailPanel remains unchanged — subscribes to `selectedSessionId` in React DOM, which is safe.
+
+### Phase 3: Verify no cross-reconciler state bridges remain
+
+- Grep for `useSessionStore`, `useCameraStore`, `useSettingsStore`, `useRoomStore` inside any component rendered within `<Canvas>`.
+- Each must use either `.getState()` in useFrame/callbacks, or receive data as props from the DOM layer.
+
+---
+
+## 10. Summary
+
+The error persists because **Zustand store updates synchronously notify subscribers in BOTH React reconcilers** (R3F and DOM). When the user clicks a robot:
+
+1. `selectSession()` notifies DOM subscribers (DetailPanel) → heavy re-render
+2. `flyTo()` notifies R3F subscribers (CameraController) → re-render inside Canvas
+3. If a WebSocket `updateSession` arrives simultaneously, SceneContent + SubagentConnections re-render
+4. Both reconcilers flush work, potentially interleaving, causing the infinite loop
+
+**The fix is architectural**: no component inside `<Canvas>` should subscribe to Zustand stores. All data flows into the Canvas via props or is read imperatively via `.getState()` in useFrame callbacks.

package/docs/PLATFORM_FEATURES_PROMPT.md

@@ -0,0 +1,296 @@
+# Prompt: Write Comprehensive Platform Features Document
+
+## Context
+
+You are documenting a full-featured **AI Agent Session Center** — a localhost dashboard (port 3333) that monitors all active AI coding agent sessions (Claude Code, Gemini CLI, Codex) in real-time via hook scripts. The platform has both a **legacy vanilla JS + CSS animations frontend** and a **React Three Fiber 3D Cyberdrome scene** built with TypeScript + Vite. The document must serve as a complete specification for rebuilding the platform from scratch.
+
+## Deliverable
+
+Write a single Markdown file `docs/PLATFORM_FEATURES.md` that exhaustively documents every feature. The document must be detailed enough that a developer who has never seen the codebase can rebuild the entire platform feature-for-feature.
+
+## Required Sections
+
+### 1. Platform Overview
+- Purpose, target users, supported AI CLIs (Claude Code, Gemini CLI, Codex, OpenClaw)
+- Tech stack: Node.js 18+ ESM, Express 5, ws 8, node-pty, better-sqlite3, React 19 + TypeScript + Vite, React Three Fiber, Zustand, IndexedDB, xterm.js
+- Architecture diagram (ASCII): Hook script → File MQ → Server → WebSocket → Browser
+- Latency expectations per stage (jq 2-5ms, file append 0.1ms, fs.watch 0-10ms, processing 0.5ms, total 3-17ms)
+
+### 2. Hook Delivery Pipeline
+- **Primary path**: bash hook script → jq enrichment (PID, TTY, terminal detection, tab_id, tmux, agent metadata) → atomic POSIX append to `/tmp/claude-session-center/queue.jsonl` → background subshell + disown
+- **Fallback**: curl HTTP POST to `localhost:PORT/api/hooks` (1s connect, 3s total timeout)
+- **MQ Reader**: fs.watch() + 10ms debounce, 500ms fallback poll, 5s health check, byte-offset tracking, partial line handling, 1MB truncation threshold
+- **Hook validation**: session_id required (max 256), event name in known set, optional claude_pid/timestamp validation
+- **Enriched fields**: claude_pid, hook_sent_at, tty_path, term_program/version, vscode_pid, tab_id (iTerm/kitty/Warp/WezTerm/Apple Terminal), tmux session/pane, terminal env vars, agent metadata (parent_session_id, team_name, agent_name/type/id/color)
+- **TTY detection cache**: per-PPID in `/tmp/claude-tty-cache/` to avoid repeated ps calls
+- **Tab title management**: escape sequences to terminal for state-changing events
+
+### 3. Hook Events and Density Levels
+- All 14 Claude events: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, Stop, Notification, SubagentStart, SubagentStop, TeammateIdle, TaskCompleted, PreCompact, SessionEnd
+- 7 Gemini events: SessionStart, BeforeAgent, BeforeTool, AfterTool, AfterAgent, SessionEnd, Notification
+- 1 Codex event: agent-turn-complete
+- 3 density levels (high=all 14, medium=12 excl TeammateIdle/PreCompact, low=5 Start/Prompt/Permission/Stop/End)
+- Hook installation: copies scripts to `~/.claude/hooks/`, atomic JSON merge into `~/.claude/settings.json`, Gemini `~/.gemini/settings.json`, Codex `~/.codex/config.toml`, Windows PowerShell variant
+
+### 4. Session State Machine
+- Full state diagram: idle → prompting → working → approval/input → waiting → idle → ended
+- All transitions with trigger events
+- Session object: 50+ fields (sessionId, projectPath, projectName, label, title, status, animationState, emote, timestamps, promptHistory[50], toolUsage Map, totalToolCalls, model, subagentCount, toolLog[200], responseLog[50], events[50], archived, source, pendingTool, waitingDetail, cachedPid, queueCount, terminalId, sshHost/Command/Config, teamId/Role, agentName/Type/Color, characterModel, accentColor, summary, previousSessions[5], tmuxPaneId, backendType)
+- Event ring buffer (500 events) for WebSocket replay on reconnect
+- Snapshot persistence: atomic write every 10s to `/tmp/claude-session-center/sessions-snapshot.json`, loaded on restart
+- Debounced broadcast: 50ms window per sessionId
+
+### 5. Session Matching (5-Priority System)
+- Priority 0: pendingResume + terminal ID or workDir match
+- Priority 0.5: auto-link to snapshot-restored ended session by projectPath (within 30 min, single candidate)
+- Priority 1: agent_terminal_id env var direct match → re-key session
+- Priority 2: tryLinkByWorkDir() pending link from sshManager
+- Priority 3: scan CONNECTING sessions by normalized path (exactly 1 match)
+- Priority 4: PID parent check via getTerminalByPtyChild()
+- Fallback: display-only card with detected terminal source (VS Code, JetBrains IDEs, iTerm, Warp, Kitty, Ghostty, Alacritty, WezTerm, Hyper, Apple Terminal, tmux)
+- Session re-keying: transfers old→new sessionId, resets state, preserves previousSessions chain, migrates SQLite FK
+
+### 6. Approval Detection
+- Tool category timeouts: fast(3s: Read/Write/Edit/Grep/Glob/NotebookEdit), userInput(3s: AskUser/EnterPlan/ExitPlan), medium(15s: WebFetch/WebSearch), slow(8s: Bash/Task)
+- hasChildProcesses check for slow tools (pgrep -P)
+- PermissionRequest event as reliable signal (medium+ density)
+- Auto-idle timeouts: prompting→30s→waiting, waiting→120s→idle, working→180s→idle, approval/input→600s→idle
+
+### 7. Team and Subagent Tracking
+- Auto-detection by matching cwd paths (parent/child within 10s window)
+- Explicit via CLAUDE_CODE_PARENT_SESSION_ID env var
+- Team config reader: `~/.claude/teams/{name}/config.json` with member metadata
+- Team terminal: attach to member's tmux pane
+- Cleanup: 15s delay after parent ends if all children also ended
+- Parent tracks subagentCount
+
+### 8. SSH/PTY Terminal Management
+- 4 creation modes: direct SSH, tmux attach, tmux wrap, resume with fallback (`claude --resume ID || claude --continue`)
+- node-pty for PTY multiplexing, max 10 concurrent
+- Shell ready detection: watches for prompt patterns ($/%/#/>), 100ms settle, 5s/15s timeouts
+- 128KB ring buffer per terminal, replayed on (re)subscribe
+- Pending workDir links for session matching (60s expiry)
+- API key injection via PTY env vars
+- AGENT_MANAGER_TERMINAL_ID env var exported on remote shell
+- Input validation: rejects shell metacharacters
+
+### 9. WebSocket Protocol
+- Server→Client: snapshot, session_update, session_removed, team_update, hook_stats, terminal_output (base64), terminal_ready, terminal_closed, clearBrowserDb, replay
+- Client→Server: terminal_input, terminal_resize, terminal_disconnect, terminal_subscribe, update_queue_count, replay (sinceSeq)
+- Heartbeat: ping 30s, pong timeout 10s
+- Backpressure: skip non-critical if send buffer >1MB
+- hook_stats throttled to 1/s
+
+### 10. REST API (All Endpoints)
+- Hook/Stats: GET/POST hook-stats, GET mq-stats
+- Sessions: GET source, POST resume, POST kill, DELETE, PUT title, PUT label, PUT accent-color, POST summarize (rate limited 2 concurrent)
+- Terminals: POST create (max 10), GET list, DELETE close
+- SSH: GET ssh-keys, POST tmux-sessions
+- Teams: GET config, POST member terminal
+- SQLite DB: GET/DELETE sessions (search/filter/paginate), GET projects, GET search (full-text), GET/POST/DELETE notes
+- Analytics: GET summary, tools, projects, heatmap (7×24)
+- Admin: POST reset, GET/POST/POST hooks status/install/uninstall
+- Auth: GET status, POST login, POST logout
+
+### 11. Authentication
+- Optional password protection via server-config.json passwordHash
+- scrypt-based hashing with timing-safe comparison
+- 24-hour in-memory tokens, hourly cleanup
+- Token sources: HTTP cookie, Authorization Bearer header, ?token= query (for WS)
+- Hook endpoints bypass auth
+
+### 12. SQLite Persistence
+- better-sqlite3, WAL mode, `data/sessions.db`
+- Tables: sessions, prompts, responses, tool_calls, events, notes (all with UNIQUE constraints)
+- Upsert pattern, batch insert transactions, cascade delete
+- Session ID migration for resume re-keying
+- Full-text LIKE search across prompts/responses
+- Analytics: prepared statements for summary, tools, projects, heatmap
+
+### 13. IndexedDB Client Persistence
+- Database: claude-dashboard v2
+- 12 object stores: sessions, prompts, responses, toolCalls, events, notes, promptQueue, alerts, sshProfiles, settings, summaryPrompts, teams
+- Batched writes: 200ms flush or 20-item threshold
+- Session dedup by timestamp on persist
+- Queue CRUD with reorder/move-between-sessions
+- Full-text search with `<mark>` highlighting
+- Timeline queries with granularity (hour/day/week/month)
+- Default seeding: 6 settings + 5 summary prompt templates
+
+### 14. CSS Character System (2D View)
+- 20 pure-CSS characters: robot, cat, alien, ghost, orb, dragon, penguin, octopus, mushroom, fox, unicorn, jellyfish, owl, bat, cactus, slime, pumpkin, yeti, crystal, bee
+- 8-color accent palette, round-robin assignment
+- Per-session character override + global setting
+- Status→animation mapping: idle→Idle, prompting→Wave+Walking, working→Running, approval/input→Waiting, waiting→ThumbsUp+Waiting, ended→Death
+- Character lifecycle: create, update (data-status attr), switch, markChecked, remove
+
+### 15. 3D Cyberdrome Scene
+- React Three Fiber + Three.js, zero useState inside Canvas (all refs), zero Zustand subscriptions inside Canvas
+- CustomEvent pattern: robot click → window.dispatchEvent('robot-select') → DOM handler → Zustand update
+- Canvas: PCFSoftShadowMap, ACESFilmicToneMapping, FOV 50, OrbitControls with damping
+- Map controls overlay: zoom in/out, top-down, reset view
+- Dynamic room system: 4 rooms/row, ROOM_SIZE=12, ROOM_GAP=5, 8 desks/room (3 north + 2 west + 3 east)
+- Two doors per room (north + south, DOOR_GAP=4)
+- Corridor workstations: 10 desks south of rooms
+- Casual areas north: Coffee Lounge (6 seats, zone -2), Gym (10 stations, zone -3)
+- Wall collision rects for navigation
+- Door waypoints with inside/outside vectors, nearest-door pathfinding
+- Robot navigation AI: 4 modes (WALK/GOTO/SIT/IDLE), status-based desk seeking, cross-room pathfinding via doors, position persistence to sessionStorage
+- Robot dialogue bubbles: status-persistent + tool-transient, zero useState (ref-based)
+- Robot labels: Billboard+Text WebGL rendering, fontSize from settings, title+status dot+alert banner
+- Status particles per robot
+- Subagent connection beams between parent/child robots
+- Scene themes synced from UI themeName setting
+- Camera controller: flyTo with smooth interpolation
+- Room labels in 3D space
+- RobotListSidebar: DOM overlay with close button, status sorting, fly-to-robot on click
+
+### 16. Session Cards (2D View)
+- Card creation with 100ms debounce
+- Pinned sessions (localStorage), muted sessions (per-session + global)
+- Top-5 tool bars with proportional fill
+- Toast notifications (error always, info configurable)
+- Label badge, team indicator, editable title
+- Status border glow pulsing
+- Drag-and-drop reorder within groups
+
+### 17. Session Detail Panel
+- Slide-in right overlay, resizable (min 320px, max 95vw), width persisted
+- Header: project name, status, model, duration, character selector, title input, label input with chips
+- 6 tabs: Conversation (prompts numbered + timestamped + COPY, previous sessions collapsible), Activity (merged events+tools+responses color-coded), Terminal (xterm.js + reconnect + theme), Notes (CRUD), Queue (per-session), Summary (AI-generated + re-summarize)
+- Tab/selection persistence in localStorage
+- Auto-attach terminal on tab switch
+- History view mode: loads from SQLite for ended sessions
+- Search integration with highlight
+
+### 18. Session Controls
+- Resume (ended sessions → terminal + `claude --resume`)
+- Kill (SIGTERM → 3s → SIGKILL, confirm modal)
+- Archive (marks archived, removes from live, plays sound)
+- Delete (permanent, cascade SQLite delete, confirm dialog)
+- Summarize (prompt template selector modal with CRUD, calls Claude haiku, rate limited)
+- Alert (timed notification modal)
+- Notes CRUD
+- Label system: 3 built-in (ONEOFF/HEAVY/IMPORTANT) + custom, chip quick-select, autocomplete history (30 max)
+- Title system: free-text, saves on blur/Enter
+
+### 19. Quick Actions
+- + NEW SESSION: full SSH modal (host/port/user/auth/key/workdir/command/tmux mode/API key/theme/title/label)
+- QUICK SESSION: minimal modal reusing last SSH config
+- ONEOFF/HEAVY/IMPORTANT: quick-launch with label pre-filled (HEAVY/IMPORTANT auto-pin)
+- MUTE ALL toggle, ARCHIVE ENDED bulk action
+- Working directory history (20 max, dropdown with delete), label history (30 max MRU)
+- Mobile FAB with slide-up panel
+- Shortcuts panel (? key)
+
+### 20. Prompt Queue
+- Per-session numbered list with SEND/expand/EDIT/MOVE/DEL per item
+- Drag-to-reorder (HTML5 drag)
+- Move mode: multi-select + choose destination session
+- Global queue view: all sessions grouped with headers
+- Auto-send: when autoSendQueue on + session→waiting, pop first item to terminal
+- IndexedDB persistence with orderIndex
+
+### 21. Session Groups
+- Default 4 groups: Priority, Active, Background, Review
+- CSS Grid 12-column layout, configurable colSpan per group
+- 5 layout presets: 1-col, 2-col, 3-col, 1/3+2/3, 2/3+1/3
+- Group CRUD, drag-reorder, resize handles
+- Session-to-group assignment via detail panel dropdown
+- Persistence in localStorage
+
+### 22. Sound System
+- 16 synthesized Web Audio API sounds: chirp, ping, chime, ding, blip, swoosh, click, beep, warble, buzz, cascade, fanfare, alarm, thud, urgentAlarm, none
+- 20 action-sound mappings (configurable per-action)
+- Per-CLI sound profiles (claude/gemini/codex/openclaw) with default overrides
+- Volume 0-1, global enable/disable
+- AudioContext unlock on first interaction
+- Ambient presets with room sounds option
+
+### 23. Movement Effects
+- 18 CSS effects: none, sweat, energy-ring, sparks, steam, eye-cycle, think-pulse, head-tilt, float, breathe, sway, sparkle, bounce, flash, shake, fade, shrink, dissolve, questions
+- Applied via data-movement attribute, auto-clear after 3.5s
+- Per-action configurable mappings
+
+### 24. Alarm System
+- Approval alarm: urgentAlarm + shake, repeats every 10s while in approval
+- Input notification: single sound on entering input state
+- Event-based: maps hook events to configured sounds/movements
+- Label completion alerts: per-label sound + movement + frame effect (fire/electric/chains/liquid/plasma)
+- Duration alerts: timed, stored in IndexedDB, checked periodically
+
+### 25. Settings
+- Appearance: 9 themes (command-center/cyberpunk/warm/dracula/solarized/nord/monokai/light/blonde), font size, card size, scanlines, activity feed, toasts
+- Sound: global enable/volume, per-action sound grid, per-CLI profiles
+- Animation: character model, intensity %, speed %, per-action movement grid
+- Hooks: density selector, install/uninstall buttons with status
+- API Keys: Anthropic/OpenAI/Gemini with show/hide
+- Label settings: per-label frame effect + sound + movement
+- Summary prompts: CRUD templates, star default, 5 built-in templates
+- Import/Export: JSON download/upload, reset to defaults
+- All settings persisted to IndexedDB with 200ms batching
+
+### 26. Terminal Manager (Frontend)
+- xterm.js with Canvas renderer, FitAddon, Unicode11Addon, WebLinksAddon
+- 10000 line scrollback, JetBrains Mono font, responsive font size
+- 8 terminal themes + auto theme (reads CSS variables)
+- Canvas repaint workaround (resize cols-1 → restore in 2 frames)
+- Fullscreen mode with Alt+F11
+- WS reconnect: clear + re-subscribe (128KB replay)
+- Pending output buffer (500 chunks max)
+- Per-terminal theme persistence
+- Resize observer with 50ms debounce
+- Team member terminal: attach to tmux pane
+
+### 27. History Panel
+- Server-side SQLite queries (not IndexedDB)
+- Filters: search (300ms debounce), project dropdown, status, date range, archived flag
+- Sort: date/duration/prompts/tools + direction toggle
+- Pagination: 50/page with numbered buttons
+- Row click → detail panel from SQLite
+- Delete with cascade fade-out
+
+### 28. Analytics Panel
+- Custom SVG charts (no library)
+- 5 sections: summary stats (6 cards), tool usage bar chart (top 15), duration trends area chart, active projects bar chart, daily heatmap (7×24 Mon-first)
+- All data from server SQLite analytics endpoints
+
+### 29. Timeline Panel
+- Grouped bar chart: sessions/prompts/tool calls per time bucket
+- Filters: granularity (hour/day/week/month), project, date range (default 30 days)
+- Data from IndexedDB getTimeline()
+
+### 30. Keyboard Shortcuts
+- `/` focus search, Escape close/deselect, `?` shortcuts panel, `S` settings, `K` kill, `A` archive, `T` new terminal, `M` mute all
+
+### 31. Server Infrastructure
+- Port conflict auto-resolution (kills occupying process)
+- Graceful shutdown (SIGTERM/SIGINT → save snapshot → close SQLite → server.close → 5s force exit)
+- Process monitor: PID liveness check every 15s
+- Auto-idle manager: per-session timers
+- Hook stats: per-event counts + latency/processing histograms
+- Rate limiting: in-memory sliding window
+- Logger: debug-aware with pretty JSON
+- Server config: port, enabledClis, hookDensity, debug, sessionHistoryHours, passwordHash
+
+### 32. CLI and Setup
+- `npx` entry: auto-setup wizard on first run, `--setup` flag to re-run
+- 6-step wizard: port, CLIs, density, debug, retention, password
+- Saves to `data/server-config.json`
+- Auto-install hooks on every server startup (quiet mode)
+
+### 33. Testing
+- Vitest unit tests (407+ tests)
+- Playwright E2E tests: groups, kill-session, navigation, session-lifecycle, settings, smoke, terminal
+
+## Instructions for Agent Team
+
+Split the work across agents:
+
+1. **Agent 1 (Server Features)**: Sections 1-12, 31-32 — everything server-side
+2. **Agent 2 (Frontend Features)**: Sections 13-21, 27-30 — UI components, panels, views
+3. **Agent 3 (3D Scene + Multimedia)**: Sections 15, 22-26, 33 — Cyberdrome, sound, animations, settings, testing
+
+Each agent should read the actual source files to verify details and add any missing specifics. The final document should be merged into a single `docs/PLATFORM_FEATURES.md` file.
+
+Write in precise technical language. Include exact values (timeouts, buffer sizes, limits). Use tables for mappings and enums. Use code blocks for data structures. Use ASCII diagrams for architecture flows.

package/docs/SESSION_DETAIL_FEATURES.md

@@ -0,0 +1,98 @@
+# Session Detail Features
+
+## Overview
+
+When a user clicks on an agent robot in the 3D Cyberdrome scene, a detail panel slides in from the right showing comprehensive session information. This document describes the features, architecture, and data flow.
+
+## Detail Panel Contents
+
+### Header
+- **Mini robot icon**: Shows first letter of model type with status-colored border
+- **Project name**: `session.projectName`
+- **Session title**: `session.title` (italic, smaller)
+- **Status badge**: Color-coded label (idle/prompting/working/waiting/approval/input/ended/connecting)
+- **Model name**: `session.model` (e.g., "claude-opus-4-6")
+- **Duration**: Time since `session.startedAt`
+
+### Session Control Bar
+- Kill, Archive, Resume buttons
+- Labels (ONEOFF, HEAVY, IMPORTANT)
+- Notes toggle
+- Summarize trigger
+
+### Tabs
+| Tab | Content |
+|-----|---------|
+| **Terminal** | xterm.js terminal connected via WebSocket relay. Shows reconnect button for SSH sessions. |
+| **Prompts** | Scrollable prompt history (`session.promptHistory`). Includes previous sessions if resumed. |
+| **Activity** | Interleaved events, tool calls, and response excerpts from `session.events`, `session.toolLog`, `session.responseLog`. |
+| **Notes** | Per-session markdown notes stored in IndexedDB. |
+| **Summary** | AI-generated session summary (`session.summary`). |
+| **Queue** | Prompt queue management — compose, reorder, send, move between sessions. |
+
+### Modals (lazy-mounted)
+- **KillConfirmModal**: Confirms session termination
+- **AlertModal**: Displays alarm notifications
+- **SummarizeModal**: Triggers AI summarization
+
+## Selection Architecture
+
+### Data Flow (Click → Detail Panel)
+
+```
+[R3F Canvas]                              [DOM Layer]
+Robot <group onClick> ──→ onSelect()      │
+  └─ SceneContent.handleSelect()          │
+       └─ setTimeout(() => {              │
+            dispatchEvent('robot-select') ──→ CyberdromeScene useEffect handler
+          })                                    ├─ selectSession(sessionId)  [sessionStore]
+                                                └─ flyTo(pos + offset)      [cameraStore]
+                                                      │
+                                          ┌───────────┘
+                                          ▼
+                                  DetailPanel (DOM)
+                                  └─ useSessionStore(selectedSessionId)
+                                     └─ Renders session details
+```
+
+### Key Principles
+
+1. **ZERO Zustand subscriptions inside `<Canvas>`**: All store reads happen in the DOM-side `CyberdromeScene` wrapper. Data flows into Canvas via props only.
+
+2. **CustomEvent bridge**: Robot clicks dispatch a `CustomEvent('robot-select')` which is caught by a DOM-side `useEffect`. This ensures Zustand store updates happen exclusively in the DOM React reconciler, never in R3F's reconciler.
+
+3. **setTimeout deferral**: The CustomEvent dispatch is wrapped in `setTimeout(0)` to ensure it fires after R3F's pointer event processing completes.
+
+4. **Imperative store reads**: Components inside Canvas that need store data (CameraController, Robot3DModel) use `useStore.getState()` inside `useFrame` instead of subscriptions.
+
+5. **Ref-based state**: Interactive state inside Canvas (hover, seated, dialogue) uses `useRef` instead of `useState` to prevent React re-renders in the R3F tree.
+
+## Store Dependencies
+
+| Component | Location | Store Subscriptions |
+|-----------|----------|-------------------|
+| CyberdromeScene | DOM wrapper | sessionStore, roomStore, settingsStore, cameraStore |
+| DetailPanel | DOM (App.tsx) | sessionStore, uiStore, wsStore |
+| RobotListSidebar | DOM overlay | sessionStore |
+| SceneOverlay | DOM overlay | roomStore, sessionStore, cameraStore, settingsStore |
+| MapControls | DOM overlay | cameraStore |
+| SceneContent | Canvas | NONE (props only) |
+| SessionRobot | Canvas | NONE (props only) |
+| CameraController | Canvas | NONE (imperative reads) |
+| Robot3DModel | Canvas | NONE (imperative reads) |
+| SubagentConnections | Canvas | NONE (props only) |
+| RoomLabels | Canvas | NONE (props only) |
+| CyberdromeEnvironment | Canvas | NONE (props only) |
+
+## Status Colors
+
+```
+idle:       #00ff88  (green)
+prompting:  #00e5ff  (cyan)
+working:    #ff9100  (orange)
+waiting:    #00e5ff  (cyan)
+approval:   #ffdd00  (yellow)
+input:      #aa66ff  (purple)
+ended:      #ff4444  (red)
+connecting: #666     (gray)
+```